Skip to main content

Environment Setup

This guide walks you through setting up the BookWish monorepo for local development.

Clone the Repository​

git clone https://github.com/yourusername/bookwish_monorepo.git
cd bookwish_monorepo

Project Structure​

The monorepo contains four main projects:

bookwish_monorepo/
├── app/          # Flutter mobile app (iOS/Android)
├── backend/      # Node.js/Express API server
├── web/          # Next.js customer-facing website
├── stores/       # Next.js bookstore websites
└── docs-site/    # Docusaurus documentation

Backend Setup​

The backend is a Node.js/Express API with PostgreSQL and Redis.

1. Install Dependencies​

cd backend
npm ci

The npm ci command installs exact versions from package-lock.json for reproducibility.

2. Configure Environment Variables​

Copy the example environment file:

cp .env.example .env

Edit .env and configure the required variables. See Environment Variables for a complete reference.

Minimum required configuration:

# Database (use Supabase or local PostgreSQL)
DATABASE_URL=postgresql://postgres:password@localhost:5432/bookwish

# Redis (local or Railway)
REDIS_URL=redis://localhost:6379

# Authentication secrets (generate with: openssl rand -hex 32)
JWT_SECRET=your_generated_secret_here
JWT_REFRESH_SECRET=your_generated_refresh_secret_here

# Book data APIs
ISBNDB_API_KEY=your_isbndb_api_key
GOOGLE_BOOKS_API_KEY=your_google_books_api_key

3. Database Setup​

Generate Prisma client:

npm run prisma:generate

Run database migrations:

npm run prisma:migrate

This creates all database tables according to the schema in prisma/schema.prisma.

(Optional) Seed the database with sample data:

npm run prisma:seed

4. Verify Backend Setup​

Start the development server:

npm run dev

The API should be running at http://localhost:3000. You should see:

Server running on port 3000
Database connected
Redis connected

Flutter App Setup​

The Flutter app supports iOS, Android, and web platforms.

1. Install Dependencies​

cd app
flutter pub get

2. Generate Code​

The app uses code generation for Riverpod state management:

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

This generates files for:

  • Riverpod providers (*.g.dart)
  • JSON serialization

For continuous code generation during development:

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

3. Configure Firebase (iOS/Android)​

The app uses Firebase for push notifications and analytics.

iOS:

  • Place GoogleService-Info.plist in app/ios/Runner/
  • The file is already configured (check git status)

Android:

  • Place google-services.json in app/android/app/
  • The file is already configured (check git status)

4. iOS-Specific Setup (macOS only)​

Install CocoaPods dependencies:

cd ios
pod install
cd ..

5. Verify Flutter Setup​

Check that everything is configured correctly:

flutter doctor -v

All check marks should be green. If you see warnings:

  • iOS toolchain: Install Xcode and run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
  • Android toolchain: Install Android Studio and accept licenses with flutter doctor --android-licenses

Web Project Setup​

The customer-facing Next.js website.

cd web
npm ci
cp .env.example .env.local

Configure the API URL in .env.local:

NEXT_PUBLIC_API_URL=http://localhost:3000/v1
NEXT_PUBLIC_APP_URL=http://localhost:3001
NEXT_PUBLIC_SITE_URL=http://localhost:3001

Stores Project Setup​

The Next.js bookstore websites platform.

cd stores
npm ci
cp .env.example .env.local

Configure in .env.local:

NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_MAIN_APP_URL=http://localhost:3001
NEXT_PUBLIC_STORES_URL=http://localhost:3002

Development Workflow​

Starting All Services​

We recommend using separate terminal windows/tabs:

Terminal 1: Backend

cd backend
npm run dev

Terminal 2: Flutter App

cd app
flutter run
# Or for web: flutter run -d chrome

Terminal 3: Web Project (optional)

cd web
npm run dev

Terminal 4: Stores Project (optional)

cd stores
npm run dev

Port Assignments​

  • Backend API: http://localhost:3000
  • Web project: http://localhost:3001
  • Stores project: http://localhost:3002
  • Prisma Studio: http://localhost:5555 (when running npx prisma studio)

Common Setup Issues​

Build Runner Issues​

If build_runner fails:

# Clean and regenerate
flutter clean
flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs

Database Connection Issues​

Error: P1001: Can't reach database server

  • Verify PostgreSQL is running: pg_isready
  • Check your DATABASE_URL format
  • If using Supabase, ensure you're using the correct connection string

Redis Connection Issues​

Error: ECONNREFUSED 127.0.0.1:6379

  • Start Redis: redis-server (or brew services start redis on macOS)
  • Verify Redis is running: redis-cli ping

iOS Build Issues​

CocoaPods errors:

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

Xcode signing issues:

  • Open app/ios/Runner.xcworkspace in Xcode
  • Select your development team in Signing & Capabilities

Android Build Issues​

SDK licenses not accepted:

flutter doctor --android-licenses

Gradle sync failed:

cd app/android
./gradlew clean
cd ..

IDE Configuration​

VS Code​

Install recommended extensions:

  • Flutter
  • Dart
  • Prisma
  • ESLint
  • TypeScript

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter: Run",
      "type": "dart",
      "request": "launch",
      "program": "app/lib/main.dart"
    }
  ]
}

Android Studio​

  1. Open the app directory as a Flutter project
  2. Configure Dart SDK path: Preferences > Languages & Frameworks > Dart
  3. Enable Flutter plugin

Next Steps​