Skip to main content

Running Locally

This guide explains how to start and run BookWish services on your local development machine.

Prerequisites​

Before starting, ensure you have:

Starting the Backend API​

The backend must be running for the mobile app and web projects to function.

Start Backend Server​

cd backend
npm run dev

Expected output:

[nodemon] starting `ts-node src/index.ts`
Server running on port 3000
Database connected ✓
Redis connected ✓
Firebase initialized ✓

Available at: http://localhost:3000

Backend Development Scripts​

# Start development server with auto-reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production build
npm start

# Run tests
npm test

# Type check without building
npm run lint

# Prisma commands
npm run prisma:migrate    # Run database migrations
npm run prisma:generate   # Generate Prisma client
npm run prisma:seed       # Seed database with sample data

Verify Backend is Running​

Test the health endpoint:

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-12-08T12:00:00.000Z"
}

Running the Flutter App​

The Flutter app can run on iOS Simulator, Android Emulator, or web browser.

iOS (macOS only)​

Start iOS Simulator:

open -a Simulator

Run the app:

cd app
flutter run

Flutter will automatically detect the iOS Simulator and install the app.

Android​

Start Android Emulator:

  • Open Android Studio > AVD Manager
  • Select an emulator and click "Run"

Or from command line:

# List available emulators
emulator -list-avds

# Start a specific emulator
emulator -avd Pixel_5_API_33

Run the app:

cd app
flutter run

Web​

cd app
flutter run -d chrome

Available at: Flutter assigns a random port - check the terminal output

Physical Devices​

iOS (requires macOS and Xcode):

  1. Connect iPhone via USB
  2. Enable Developer Mode on iPhone: Settings > Privacy & Security > Developer Mode
  3. Trust your Mac on the iPhone when prompted
  4. Run: flutter run

Android:

  1. Enable Developer Options on Android device
  2. Enable USB Debugging
  3. Connect via USB
  4. Run: flutter run

Flutter Development Commands​

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

# List available devices
flutter devices

# Run with specific flavor (if configured)
flutter run --flavor dev

# Clean build cache
flutter clean

# Get dependencies
flutter pub get

# Run code generation (Riverpod)
flutter pub run build_runner build --delete-conflicting-outputs

# Watch mode for code generation
flutter pub run build_runner watch --delete-conflicting-outputs

# Run tests
flutter test

# Analyze code
flutter analyze

Hot Reload & Hot Restart​

When the app is running:

  • Hot Reload: Press r in the terminal (applies code changes without restarting)
  • Hot Restart: Press R (restarts the app completely)
  • Quit: Press q

Hot reload preserves app state and is very fast. Use hot restart if hot reload doesn't work (e.g., after changing dependencies or app initialization).

Running Web Projects​

Customer-Facing Website (Next.js)​

cd web
npm run dev

Available at: http://localhost:3001 (default Next.js port 3000, adjusted to avoid conflict)

Bookstore Websites (Next.js)​

cd stores
npm run dev

Available at: http://localhost:3002

Access a specific store:

  • Development: http://localhost:3002?store=store-slug
  • Or configure local DNS for testing custom domains

Web Development Commands​

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

Running All Services Together​

For full-stack development, run these in separate terminal windows/tabs:

Terminal 1: Backend

cd backend && npm run dev

Terminal 2: Flutter (choose one)

# iOS
cd app && flutter run

# Android
cd app && flutter run

# Web
cd app && flutter run -d chrome

Terminal 3: Web Project (optional)

cd web && npm run dev

Terminal 4: Stores Project (optional)

cd stores && npm run dev

Terminal 5: Code Generation (optional, for Flutter)

cd app && flutter pub run build_runner watch --delete-conflicting-outputs

Terminal 6: Prisma Studio (optional, for database browsing)

cd backend && npx prisma studio

Service Verification​

Check Backend Health​

# Health check
curl http://localhost:3000/health

# Test authentication endpoint
curl http://localhost:3000/v1/auth/guest -X POST

# View API documentation (if configured)
curl http://localhost:3000/v1/docs

Check Database Connection​

cd backend
npx prisma studio

Opens Prisma Studio at http://localhost:5555 for visual database browsing.

Check Redis Connection​

redis-cli ping
# Should return: PONG

# Monitor Redis activity
redis-cli monitor

Check Flutter App​

The app should connect to the backend API automatically. Check the debug console for:

API connected: http://localhost:3000

Development Workflow​

Typical Development Session​

  1. Start backend (Terminal 1)

    cd backend && npm run dev

  2. Start code generation (Terminal 2)

    cd app && flutter pub run build_runner watch

  3. Run Flutter app (Terminal 3)

    cd app && flutter run

  4. Make changes:

    • Edit code in your IDE
    • Save files
    • Press r in the Flutter terminal for hot reload
    • Backend auto-reloads with nodemon

  5. Test changes:

    • Interact with the app
    • Check backend logs
    • Use Prisma Studio to inspect database

Code Generation Workflow​

When adding new Riverpod providers or modifying existing ones:

  1. Add/modify provider code with @riverpod annotation
  2. Save the file
  3. build_runner watch automatically regenerates the .g.dart file
  4. Press r in Flutter terminal to hot reload

Manual generation:

flutter pub run build_runner build --delete-conflicting-outputs

Database Migration Workflow​

When modifying the Prisma schema:

  1. Edit backend/prisma/schema.prisma
  2. Create migration: 
    cd backend
    npm run prisma:migrate
    # Enter migration name when prompted
  3. Migration is automatically applied
  4. Prisma Client is regenerated

Testing API Changes​

Use curl, Postman, or Insomnia:

# Create guest user
curl -X POST http://localhost:3000/v1/auth/guest

# Get books
curl -X GET http://localhost:3000/v1/books

# Search books
curl -X GET "http://localhost:3000/v1/books/search?q=gatsby"

Port Reference​

ServicePortURL
Backend API3000http://localhost:3000
Web (Next.js)3001http://localhost:3001
Stores (Next.js)3002http://localhost:3002
Prisma Studio5555http://localhost:5555
Flutter WebAuto(auto-assigned port)
PostgreSQL5432localhost:5432
Redis6379localhost:6379

Common Development Tasks​

Reset Database​

cd backend

# Drop all tables and re-run migrations
npx prisma migrate reset

# Seed with sample data
npm run prisma:seed

Warning: This deletes all data. Use only in development.

Clear Redis Cache​

redis-cli FLUSHALL

Rebuild Flutter App​

cd app

# Clean build artifacts
flutter clean

# Get dependencies
flutter pub get

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

# Run app
flutter run

View Backend Logs​

Backend logs are printed to the terminal. For structured logging:

cd backend
npm run dev | tee logs.txt

Debugging​

Flutter:

  • VS Code: Use Debug > Start Debugging (F5)
  • Android Studio: Click the debug icon
  • DevTools: flutter run automatically opens DevTools

Backend:

  • VS Code: Add debug configuration in .vscode/launch.json
  • Use console.log() or logger.info() for logging

Common Issues​

Port Already in Use​

Error: Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or use a different port
PORT=3001 npm run dev

Flutter App Not Connecting to Backend​

  1. Check backend is running on http://localhost:3000
  2. Verify API URL in Flutter app configuration
  3. For iOS Simulator: Use localhost
  4. For Android Emulator: Use 10.0.2.2 instead of localhost
  5. For physical device: Use your computer's IP address

Build Runner Conflicts​

Error: Conflicting outputs were detected

Solution:

flutter pub run build_runner build --delete-conflicting-outputs

iOS Pod Install Fails​

cd app/ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ../..

Database Migration Issues​

If migrations fail, check:

  1. PostgreSQL is running
  2. DATABASE_URL is correct
  3. Database exists and is accessible

Reset and retry:

cd backend
npx prisma migrate reset
npm run prisma:migrate

Performance Tips​

Backend​

  • Use npm run dev for auto-reload (faster than manual restarts)
  • Keep Redis running to avoid reconnection delays
  • Use Prisma Studio instead of raw SQL queries for debugging

Flutter​

  • Use hot reload (r) instead of hot restart when possible
  • Run build_runner watch in a separate terminal
  • Use Flutter DevTools for performance profiling
  • Keep the emulator/simulator running between sessions

Web Projects​

  • Next.js Fast Refresh is automatic
  • Disable unnecessary API calls in development
  • Use browser DevTools for debugging

Next Steps​