retail/docs/BARREL_EXPORTS_QUICK_REFERENCE.md

Barrel Exports Quick Reference

Quick Import Guide

Complete Feature Import

// Import entire auth feature (all layers)
import 'package:retail/features/auth/auth.dart';

// Import entire products feature
import 'package:retail/features/products/products.dart';

// Import entire categories feature
import 'package:retail/features/categories/categories.dart';

// Import entire home/cart feature
import 'package:retail/features/home/home.dart';

// Import entire settings feature
import 'package:retail/features/settings/settings.dart';

// Import ALL features at once
import 'package:retail/features/features.dart';

Layer-Specific Imports

// Auth layers
import 'package:retail/features/auth/data/data.dart';         // Data layer only
import 'package:retail/features/auth/domain/domain.dart';     // Domain layer only
import 'package:retail/features/auth/presentation/presentation.dart'; // Presentation only

// Products layers
import 'package:retail/features/products/data/data.dart';
import 'package:retail/features/products/domain/domain.dart';
import 'package:retail/features/products/presentation/presentation.dart';

// Categories layers
import 'package:retail/features/categories/data/data.dart';
import 'package:retail/features/categories/domain/domain.dart';
import 'package:retail/features/categories/presentation/presentation.dart';

// Home/Cart layers
import 'package:retail/features/home/data/data.dart';
import 'package:retail/features/home/domain/domain.dart';
import 'package:retail/features/home/presentation/presentation.dart';

// Settings layers
import 'package:retail/features/settings/data/data.dart';
import 'package:retail/features/settings/domain/domain.dart';
import 'package:retail/features/settings/presentation/presentation.dart';

Component-Specific Imports

// Models
import 'package:retail/features/products/data/models/models.dart';
import 'package:retail/features/auth/data/models/models.dart';

// Entities
import 'package:retail/features/products/domain/entities/entities.dart';
import 'package:retail/features/home/domain/entities/entities.dart';

// Use Cases
import 'package:retail/features/products/domain/usecases/usecases.dart';
import 'package:retail/features/categories/domain/usecases/usecases.dart';

// Providers
import 'package:retail/features/products/presentation/providers/providers.dart';
import 'package:retail/features/home/presentation/providers/providers.dart';

// Pages
import 'package:retail/features/products/presentation/pages/pages.dart';
import 'package:retail/features/auth/presentation/pages/pages.dart';

// Widgets
import 'package:retail/features/products/presentation/widgets/widgets.dart';
import 'package:retail/features/auth/presentation/widgets/widgets.dart';

Core Utilities

// All core utilities
import 'package:retail/core/core.dart';

// Specific core modules
import 'package:retail/core/constants/constants.dart';   // All constants
import 'package:retail/core/theme/theme.dart';           // Theme configuration
import 'package:retail/core/network/network.dart';       // HTTP & network
import 'package:retail/core/errors/errors.dart';         // Exceptions & failures
import 'package:retail/core/utils/utils.dart';           // Utilities & helpers
import 'package:retail/core/di/di.dart';                 // Dependency injection
import 'package:retail/core/database/database.dart';     // Hive database
import 'package:retail/core/storage/storage.dart';       // Secure storage
import 'package:retail/core/widgets/widgets.dart';       // Core widgets

Shared Components

// Shared widgets and components
import 'package:retail/shared/shared.dart';

Common Use Cases

Building a Page

// In a page file, you typically need presentation layer
import 'package:retail/features/products/presentation/presentation.dart';
// This gives you: pages, widgets, providers

Implementing a Repository

// In repository implementation, import domain interfaces
import 'package:retail/features/products/domain/domain.dart';
// This gives you: entities, repository interfaces, use cases

Creating a Provider

// In a provider, import domain layer and other providers
import 'package:retail/features/products/domain/domain.dart';
import 'package:retail/features/products/presentation/providers/providers.dart';

Using Multiple Features

// When you need multiple features
import 'package:retail/features/products/products.dart';
import 'package:retail/features/categories/categories.dart';
import 'package:retail/core/core.dart';

Layer Dependencies (Important!)

Allowed Dependencies

Presentation Layer:
  ✅ Can import: domain, core, shared
  ❌ Cannot import: data

Data Layer:
  ✅ Can import: domain, core
  ❌ Cannot import: presentation

Domain Layer:
  ✅ Can import: core (only exceptions/interfaces)
  ❌ Cannot import: data, presentation

Core:
  ✅ Can import: nothing (self-contained)
  ❌ Cannot import: features

Shared:
  ✅ Can import: core
  ❌ Cannot import: features (to avoid circular dependencies)

Example: Correct Dependencies

// ✅ GOOD: Presentation imports domain
// In: features/products/presentation/pages/products_page.dart
import 'package:retail/features/products/domain/domain.dart';
import 'package:retail/core/core.dart';

// ✅ GOOD: Data imports domain
// In: features/products/data/repositories/product_repository_impl.dart
import 'package:retail/features/products/domain/domain.dart';
import 'package:retail/core/core.dart';

// ✅ GOOD: Domain is independent
// In: features/products/domain/entities/product.dart
import 'package:retail/core/errors/errors.dart'; // Only core exceptions

// ❌ BAD: Domain importing data or presentation
// In: features/products/domain/usecases/get_products.dart
import 'package:retail/features/products/data/data.dart'; // NEVER!
import 'package:retail/features/products/presentation/presentation.dart'; // NEVER!

Import Decision Tree

1. Do I need the entire feature?
   ├─ Yes → import 'features/[feature]/[feature].dart'
   └─ No → Continue to 2

2. Do I need an entire layer?
   ├─ Yes → import 'features/[feature]/[layer]/[layer].dart'
   └─ No → Continue to 3

3. Do I need specific components?
   └─ Yes → import 'features/[feature]/[layer]/[component]/[component].dart'

4. Is it a core utility?
   ├─ All utilities → import 'core/core.dart'
   └─ Specific module → import 'core/[module]/[module].dart'

5. Is it a shared component?
   └─ Yes → import 'shared/shared.dart'

Migration from Direct Imports

Before (Direct Imports - Fragile)

import 'package:retail/features/products/data/models/product_model.dart';
import 'package:retail/features/products/data/datasources/product_local_datasource.dart';
import 'package:retail/features/products/data/repositories/product_repository_impl.dart';
import 'package:retail/features/products/domain/entities/product.dart';
import 'package:retail/features/products/domain/repositories/product_repository.dart';
import 'package:retail/features/products/presentation/pages/products_page.dart';
import 'package:retail/features/products/presentation/widgets/product_card.dart';
import 'package:retail/features/products/presentation/widgets/product_grid.dart';
import 'package:retail/core/constants/api_constants.dart';
import 'package:retail/core/theme/colors.dart';

After (Barrel Imports - Clean & Maintainable)

import 'package:retail/features/products/products.dart';
import 'package:retail/core/core.dart';

Special Notes

Products Providers

The products feature has all providers consolidated in products_provider.dart:

// Import all product providers at once
import 'package:retail/features/products/presentation/providers/providers.dart';

// This includes:
// - productsProvider (list of products)
// - searchQueryProvider (search state)
// - filteredProductsProvider (filtered results)

Selected Category Provider

The selectedCategoryProvider exists in multiple places:

• In categories_provider.dart (for category management)
• In products/selected_category_provider.dart (for product filtering)

Use the one from products when filtering products:

import 'package:retail/features/products/presentation/providers/providers.dart';
// Use: selectedCategoryProvider for product filtering

Core Providers

Core providers are in core/providers/providers.dart:

import 'package:retail/core/providers/providers.dart';
// Includes: networkInfoProvider, syncStatusProvider

Tips for Best Practices

1. Start broad, narrow down if needed

   • Try feature-level import first
   • Move to layer-level if you only need one layer
   • Use component-level for very specific needs

2. Avoid circular dependencies

   • Domain never imports from data/presentation
   • Features don't import from each other (use shared instead)

3. Use IDE autocomplete

   • Type import 'package:retail/ and let IDE suggest
   • Barrel exports will show up clearly

4. Keep imports organized

   // 1. Dart/Flutter imports
   import 'package:flutter/material.dart';
   
   // 2. Third-party packages
   import 'package:riverpod_annotation/riverpod_annotation.dart';
   
   // 3. Project features
   import 'package:retail/features/products/products.dart';
   
   // 4. Core utilities
   import 'package:retail/core/core.dart';
   
   // 5. Shared components
   import 'package:retail/shared/shared.dart';
   

5. Update barrel exports when adding files

   • Added new model? Update models/models.dart
   • Added new page? Update pages/pages.dart
   • New use case? Update usecases/usecases.dart

File Locations Reference

Core Barrel Exports:
  /lib/core/core.dart
  /lib/core/config/config.dart
  /lib/core/constants/constants.dart
  /lib/core/database/database.dart
  /lib/core/di/di.dart
  /lib/core/errors/errors.dart
  /lib/core/network/network.dart
  /lib/core/storage/storage.dart
  /lib/core/theme/theme.dart
  /lib/core/utils/utils.dart

Feature Barrel Exports:
  /lib/features/features.dart
  /lib/features/auth/auth.dart
  /lib/features/products/products.dart
  /lib/features/categories/categories.dart
  /lib/features/home/home.dart
  /lib/features/settings/settings.dart

Shared Barrel Exports:
  /lib/shared/shared.dart

Quick Command Reference

# Find all barrel export files
find lib -name "*.dart" -type f | grep -E "\/(data|domain|presentation|entities|models|usecases|providers|pages|widgets|datasources|constants|errors|network|storage|theme|utils|di|config|database)\.dart$"

# Check for ambiguous exports
flutter analyze | grep "ambiguous_export"

# Verify imports compile
flutter analyze

---

Remember: Barrel exports make your code cleaner, more maintainable, and easier to refactor!