Canonical import patterns for consistent, maintainable code across the entire codebase

Import Path Standards

Overview

This guide establishes canonical import paths for all modules in our project. By following these standards, we ensure consistency across documentation, examples, and actual code implementation.

Why canonical imports matter: They reduce cognitive load, speed up development, and eliminate the "which import should I use?" decision fatigue. When everyone uses the same import patterns, code reviews focus on logic rather than style choices.

Core Principle

Single Source of Truth: Each module has ONE canonical import path used consistently across:

Code implementation
Documentation examples
Type definitions
Test files

Canonical Import Patterns

Theme Management

// ✅ CANONICAL - Always use these patterns
import { useTheme } from '@/core/shared/styles';
import { ThemeProvider } from '@/core/shared/styles';
import { Theme } from '@/core/shared/styles';
 
// ❌ AVOID - Common incorrect variations
import { useTheme } from '@core/shared/styles';           // Missing @/ prefix
import { useTheme } from '@/core/shared/styles/ThemeProvider'; // Too specific
import { useTheme } from '@/core/theme';                 // Non-canonical path

Domain Logic (Cross-Feature Business Logic)

// ✅ CANONICAL - For shared business entities and logic
import { useProducts } from '@/core/domains/products';
import { Product } from '@/core/domains/products';
import { useAuth } from '@/core/domains/auth';
import { User } from '@/core/domains/auth';
 
// ❌ AVOID - Specific file paths
import { useProducts } from '@/core/domains/products/hooks';
import { Product } from '@/core/domains/products/types';

Feature Logic (Feature-Specific Logic)

// ✅ CANONICAL - For feature-specific behavior
import { useCart } from '@/features/cart/hooks';
import { useCheckoutFlow } from '@/features/checkout/hooks';
import { ProductFilters } from '@/features/catalog/components';
 
// ❌ AVOID - Specific file paths
import { useCart } from '@/features/cart/hooks/useCart';
import { ProductFilters } from '@/features/catalog/components/ProductFilters';

UI Components

// ✅ CANONICAL - Direct component imports
import { Button } from '@/ui/foundation/Button';
import { Modal } from '@/ui/patterns/Modal';
import { ProductCard } from '@/ui/business/ProductCard';
 
// ❌ AVOID - File extensions or nested paths
import { Button } from '@/ui/foundation/Button/Button';
import { Modal } from '@/ui/patterns/Modal/Modal.tsx';

Shared Utilities

// ✅ CANONICAL - Barrel exports for utilities
import { formatCurrency } from '@/core/shared/utils';
import { useDebounce } from '@/core/shared/hooks';
 
// ❌ AVOID - Specific file paths
import { formatCurrency } from '@/core/shared/utils/number';
import { useDebounce } from '@/core/shared/hooks/useDebounce';

Architecture Decision Guide

Understanding when to use domain vs feature imports is crucial for maintainable architecture:

Domain Logic (`@/core/domains/[domain]`)

Use when your code:

Is used by 3+ features
Represents core business entities (User, Product, Order)
Contains cross-cutting business rules
Needs to be highly reusable and stable

Examples:

// User authentication used across app
import { useAuth, User } from '@/core/domains/auth';
 
// Product data used by catalog, search, cart, checkout
import { useProducts, Product } from '@/core/domains/products';
 
// Order management used by checkout, history, tracking
import { useOrders, Order } from '@/core/domains/orders';

Real-world scenarios:

User profile data accessed from navigation, settings, and checkout
Product information displayed in lists, details, and cart
Order status shown in checkout confirmation and order history

Import Structure Requirements

Path Alias Standards

All imports must use the @/ prefix for consistency:

// ✅ CORRECT - Consistent @/ prefix
import { useTheme } from '@/core/shared/styles';
import { useProducts } from '@/core/domains/products';
import { Button } from '@/ui/foundation/Button';
 
// ❌ INCORRECT - Missing @/ prefix
import { useTheme } from '@core/shared/styles';
import { useProducts } from '@core/domains/products';

Barrel Exports Required

Every module directory must have an index.ts that exports the public API:

Domain Module Example

// src/core/domains/products/index.ts
export { useProducts, useProduct, useProductSearch } from './hooks';
export { Product, ProductCategory, ProductFilter } from './types';
export { productApi } from './api';
export { productUtils } from './utils';

UI Component Example

// src/ui/foundation/Button/index.ts
export { Button } from './Button';
export type { ButtonProps, ButtonVariant } from './types';

Feature Module Example

// src/features/cart/hooks/index.ts
export { useCart } from './useCart';
export { useCartPersistence } from './useCartPersistence';
export { useCartValidation } from './useCartValidation';

Import Order Convention

Follow this order for clean, predictable imports:

// 1. React/React Native
import React from 'react';
import { View, Text } from 'react-native';
 
// 2. Third-party libraries  
import { useQuery } from '@tanstack/react-query';
 
// 3. Theme (highest priority internal)
import { useTheme } from '@/core/shared/styles';
 
// 4. Domain imports
import { useProducts } from '@/core/domains/products';
 
// 5. UI components
import { Button } from '@/ui/foundation/Button';
 
// 6. Feature imports
import { useCart } from '@/features/cart/hooks';
 
// 7. Relative imports (same directory only)
import { styles } from './styles';

Documentation Standards

Code Examples in Documentation

All documentation examples must use canonical import paths:

// ✅ ALWAYS in documentation
import { useTheme } from '@/core/shared/styles';
import { Button } from '@/ui/foundation/Button';
import { useProducts } from '@/core/domains/products';
 
// ❌ NEVER in documentation
import { useTheme } from '@core/shared/styles';        // Missing @/ prefix
import { Button } from '@/ui/foundation/Button/Button'; // Too specific

Cross-References

When linking to other guides, reference the canonical source rather than duplicating information:

// ✅ Proper cross-reference
For theme customization, see [Theme Management](/docs/ui-development/theme-management).
 
// ❌ Improper duplication
You can also define custom themes by creating a theme object...

Migration Strategies

Updating Existing Code

When refactoring imports to follow these standards:

Identify Current Patterns

Search your codebase for non-canonical imports:

# Find missing @/ prefixes
grep -r "from '@ui" src/
grep -r "from '@core" src/
grep -r "from '@features" src/
 
# Find overly specific paths
grep -r "from '@/.*/.*/" src/

Update to Canonical Patterns

Replace with canonical imports:

// Before
import { useTheme } from '@core/shared/styles';
import { Button } from '@/ui/foundation/Button/Button';
 
// After  
import { useTheme } from '@/core/shared/styles';
import { Button } from '@/ui/foundation/Button';

Verify Barrel Exports

Ensure all modules have proper barrel exports:

// Check that index.ts files exist and export correctly
// src/core/domains/products/index.ts
// src/ui/foundation/Button/index.ts
// src/features/cart/hooks/index.ts

Automated Tools

Consider these tools for maintaining import consistency:

ESLint rules for import path validation
Pre-commit hooks for import checking
IDE settings for auto-import configuration

Benefits

Following these import standards provides:

Consistent Learning: Developers learn one import pattern
Easier Refactoring: Changes only need updates in one place
Clear Dependencies: Import paths show architectural relationships
Reduced Confusion: No guessing which import to use
Better Tooling: IDEs provide better autocomplete and navigation

Common Patterns Reference

Code Type	Location	Import Pattern	Example
Theme	Core Shared	`@/core/shared/styles`	`useTheme`
Domain Logic	Core Domains	`@/core/domains/[domain]`	`useProducts`
Feature Logic	Features	`@/features/[feature]/hooks`	`useCart`
Foundation UI	UI Foundation	`@/ui/foundation/[component]`	`Button`
Pattern UI	UI Patterns	`@/ui/patterns/[component]`	`Modal`
Business UI	UI Business	`@/ui/business/[component]`	`ProductCard`
Shared Utils	Core Shared	`@/core/shared/utils`	`formatCurrency`

Pro tip: Bookmark this reference table! Most import decisions can be made quickly by checking the code type and following the corresponding pattern.

Troubleshooting

Common Issues

Import not found errors:

Verify the barrel export exists in the target module's index.ts
Check that the @/ prefix is included
Ensure the path matches the actual directory structure

Multiple ways to import the same thing:

Always choose the canonical pattern from this guide
When in doubt, use the most general path (barrel export over specific file)

IDE not suggesting correct imports:

Configure your IDE's auto-import settings to prefer canonical paths
Update tsconfig.json path mappings if necessary

For additional guidance, see the Feature Implementation Decision Tree for architectural placement decisions.

Import Path Standards

On this page