renolation/retail
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
77440ac95736ccffbdbb43de3d01832d8108822e
retail/docs/RUN_APP.md
Phuoc Nguyen b94c158004 runable
2025-10-10 16:38:07 +07:00

10 KiB
Raw Blame History

Quick Start Guide - Retail POS App

Prerequisites

  1. Flutter SDK (3.35.x or higher)

    flutter --version

  2. Dart SDK (3.9.2 or higher)

    dart --version

  3. Connected Device or Emulator

    flutter devices

Initial Setup

1. Install Dependencies

cd /Users/ssg/project/retail
flutter pub get

2. Generate Code

This step is CRITICAL - the app won't run without it!

# Generate all Riverpod and Hive code
flutter pub run build_runner build --delete-conflicting-outputs

What this does:

  • Generates .g.dart files for all providers
  • Generates Hive type adapters
  • Creates necessary code for dependency injection

Watch mode (for development):

# Automatically regenerates when files change
flutter pub run build_runner watch --delete-conflicting-outputs

3. Verify Code Generation

Check that these files exist:

# Check providers were generated
ls lib/features/home/presentation/providers/*.g.dart
ls lib/features/products/presentation/providers/*.g.dart
ls lib/features/categories/presentation/providers/*.g.dart
ls lib/features/settings/presentation/providers/*.g.dart

# Check models were generated
ls lib/features/home/data/models/*.g.dart
ls lib/features/products/data/models/*.g.dart
ls lib/features/categories/data/models/*.g.dart
ls lib/features/settings/data/models/*.g.dart

Running the App

Option 1: Default Device

flutter run

Option 2: Specific Device

# List available devices
flutter devices

# Run on specific device
flutter run -d <device-id>

# Examples:
flutter run -d chrome           # Web
flutter run -d macos            # macOS
flutter run -d emulator-5554    # Android emulator
flutter run -d "iPhone 15"      # iOS simulator

Option 3: Release Mode

flutter run --release

Option 4: With Hot Reload (Development)

# Run in debug mode with hot reload enabled
flutter run

# While running:
# Press 'r' to hot reload
# Press 'R' to hot restart
# Press 'h' for help
# Press 'q' to quit

Development Workflow

Run with Watch Mode

Open two terminals:

Terminal 1: Run build_runner in watch mode

cd /Users/ssg/project/retail
flutter pub run build_runner watch --delete-conflicting-outputs

Terminal 2: Run the app

cd /Users/ssg/project/retail
flutter run

This allows:

  • Automatic code regeneration when you modify providers
  • Hot reload for UI changes
  • Continuous development without manual rebuilds

Common Commands

Clean Build

# Clean build artifacts
flutter clean

# Get dependencies again
flutter pub get

# Regenerate code
flutter pub run build_runner build --delete-conflicting-outputs

# Run app
flutter run

Analyze Code

# Check for issues
flutter analyze

# Format code
dart format .

# Fix formatting
dart fix --apply

Testing

# Run all tests
flutter test

# Run specific test
flutter test test/path/to/test_file.dart

# With coverage
flutter test --coverage

Build for Production

Android APK:

flutter build apk --release
# Output: build/app/outputs/flutter-apk/app-release.apk

Android App Bundle:

flutter build appbundle --release
# Output: build/app/outputs/bundle/release/app-release.aab

iOS:

flutter build ios --release

macOS:

flutter build macos --release

Web:

flutter build web --release
# Output: build/web/

Troubleshooting

Issue: "No providers found" or "Provider not generated"

Solution:

# Delete old generated files
flutter clean

# Reinstall dependencies
flutter pub get

# Regenerate all code
flutter pub run build_runner build --delete-conflicting-outputs

Issue: "MissingPluginException"

Solution:

# Stop the app
# Clean and rebuild
flutter clean
flutter pub get
flutter run

Issue: Hive errors

Solution: Check that Hive boxes are registered in main.dart:

// Ensure these are uncommented after code generation:
Hive.registerAdapter(ProductModelAdapter());
Hive.registerAdapter(CategoryModelAdapter());
Hive.registerAdapter(CartItemModelAdapter());
Hive.registerAdapter(AppSettingsModelAdapter());

Issue: Build runner conflicts

Solution:

# Use delete-conflicting-outputs flag
flutter pub run build_runner build --delete-conflicting-outputs

Issue: Hot reload not working

Solution:

# Press 'R' for hot restart instead of 'r'
# Or restart the app entirely
flutter run

App Features Overview

Once running, you can:

1. Home Tab (POS)

  • View available products in a grid
  • Tap product to add to cart
  • Adjust quantity before adding
  • View cart with items and total
  • Manage cart quantities
  • Clear cart
  • Checkout (when implemented)

2. Products Tab

  • Search products by name/description
  • Filter by category using chips
  • Sort products (name, price, date)
  • Pull to refresh
  • Responsive grid layout

3. Categories Tab

  • View all categories in a grid
  • See product count per category
  • Tap category to filter products
  • Pull to refresh

4. Settings Tab

  • Change theme (Light/Dark/System)
  • Select language
  • Choose currency
  • Set store name
  • Configure tax rate
  • Sync data
  • Clear cache
  • View app info

Development Tips

1. Use VS Code Extensions

  • Flutter (Dart-Code.flutter)
  • Dart (Dart-Code.dart-code)
  • Flutter Riverpod Snippets
  • Error Lens (usernamehw.errorlens)

2. Enable DevTools

# While app is running
flutter run

# Open DevTools in browser
# Click the URL shown in terminal (e.g., http://127.0.0.1:9101/)

3. Use Flutter Inspector

  • Open DevTools
  • Click "Flutter Inspector" tab
  • Inspect widget tree
  • Debug layout issues
  • Toggle debug paint
  • Measure render times

4. Performance Profiling

# Run in profile mode
flutter run --profile

# Open DevTools > Performance
# Record timeline
# Analyze frame rendering

5. Hot Reload Tips

  • Works for UI changes
  • Doesn't work for:
    • Adding new dependencies
    • Changing provider annotations
    • Modifying main()
  • Use Hot Restart (R) for those changes

Project Structure Quick Reference

lib/
├── main.dart                          # Entry point - START HERE
├── app.dart                           # App shell with tabs
│
├── features/
│   ├── home/presentation/pages/home_page.dart           # Home/POS page
│   ├── products/presentation/pages/products_page.dart   # Products page
│   ├── categories/presentation/pages/categories_page.dart # Categories page
│   └── settings/presentation/pages/settings_page.dart   # Settings page
│
└── core/
    ├── theme/app_theme.dart           # Material 3 themes
    └── constants/                     # App constants

Quick Commands Cheat Sheet

# Setup
flutter pub get                                              # Install dependencies
flutter pub run build_runner build --delete-conflicting-outputs  # Generate code

# Run
flutter run                                                  # Run app
flutter run -d chrome                                        # Run on web
flutter run --release                                        # Release mode

# Development
flutter pub run build_runner watch --delete-conflicting-outputs  # Watch mode
dart format .                                                # Format code
flutter analyze                                              # Analyze code

# Build
flutter build apk --release                                  # Android APK
flutter build appbundle --release                            # Android Bundle
flutter build ios --release                                  # iOS
flutter build web --release                                  # Web

# Testing
flutter test                                                 # Run tests
flutter test --coverage                                      # With coverage

# Maintenance
flutter clean                                                # Clean build
flutter doctor                                               # Check environment
flutter upgrade                                              # Upgrade Flutter

Environment Verification

Before running, verify your setup:

# Check Flutter installation
flutter doctor -v

# Should show:
# ✓ Flutter (version 3.35.x or higher)
# ✓ Dart (version 3.9.2 or higher)
# ✓ Android toolchain (if targeting Android)
# ✓ Xcode (if targeting iOS/macOS)
# ✓ Connected devices

# Check dependencies
flutter pub get

# Verify pubspec.lock exists
ls pubspec.lock

# Check generated files
ls lib/**/*.g.dart

Expected Output

When running successfully, you should see:

Launching lib/main.dart on <device> in debug mode...
Running Gradle task 'assembleDebug'...
✓ Built build/app/outputs/flutter-apk/app-debug.apk.

Flutter run key commands.
r Hot reload.
R Hot restart.
h List all available interactive commands.
d Detach (terminate "flutter run" but leave application running).
c Clear the screen
q Quit (terminate the application on the device).

An Observatory debugger and profiler on <device> is available at: http://127.0.0.1:xxxxx/
The Flutter DevTools debugger and profiler on <device> is available at: http://127.0.0.1:9100/

Next Steps After Running

  1. Explore the App:

    • Navigate through all 4 tabs
    • Try adding products to cart
    • Search and filter products
    • Change theme in settings

  2. Check Functionality:

    • Add items to cart
    • Remove items from cart
    • Filter by category
    • Search products
    • Sort products
    • Change settings

  3. Test Responsiveness:

    • Resize window (if on desktop/web)
    • Try portrait and landscape (if on mobile)
    • Check different screen sizes

  4. Review Code:

    • Check generated .g.dart files
    • Review provider implementations
    • Understand the flow

Support

If you encounter issues:

  1. Check flutter doctor output
  2. Ensure code generation completed successfully
  3. Review error messages in the terminal
  4. Check PAGES_SUMMARY.md for known issues
  5. Verify all dependencies in pubspec.yaml are compatible

Ready to Go!

# Quick start (copy-paste):
cd /Users/ssg/project/retail && \
flutter pub get && \
flutter pub run build_runner build --delete-conflicting-outputs && \
flutter run

Happy coding! 🚀