This monorepo integrates a Medusa backend, PayloadCMS, Next.js storefront, Drizzle Studio, and an email app for seamless ecommerce development.

1. Environment Configuration: Create .env files from templates:

   # Root level .env for Docker services
   cp .env.template .env
   
   # Medusa app .env
   cp apps/medusa/.env.template apps/medusa/.env

2. Start Docker Services (PostgreSQL & Redis):

   pnpm docker:up

3. Install Dependencies:

   pnpm install

4. Database Setup:

   cd apps/medusa
   pnpm migrate

5. Create Admin User:

   npx medusa user -e email@gmail.com -p StrongPassword123

6. Seed Sample Data:

   pnpm seed

7. Configure Publishable Key:

   • Start Medusa backend: pnpm dev
   • Open Medusa Admin at backoffice_url/app
   • Go to Settings → API Key Management
   • Copy the publishable key
   • Add it to storefront .env:

     NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_your_key_here
     MEDUSA_PUBLISHABLE_KEY=pk_your_key_here
     

8. Setup Storefront (if using PayloadCMS):

   cd ../storefront
   # Copy environment template and configure
   cp .env.template .env
   
   # Run migrations to create database schema
   npx payload migrate
   
   # If you encounter "users_sessions table missing" error:
   npx payload migrate:create  # Generate missing tables migration
   npx payload migrate         # Apply the new migration
   
   cd ../..

9. Access Database UI (optional - for database management):

   # Database visualization will be available at http://localhost:4983
   # Starts automatically with docker compose
   # Default master password: admin123
   # Use this connection URL: postgresql://user:pass@postgres:5432/postgres_db
   # Note: Use 'postgres' as host (not localhost) because both the database 
   # visualization and PostgreSQL are in the same Docker network

pnpx turbo run dev

1. Start Services First:

   # Start Docker containers (PostgreSQL, Redis)
   docker compose up -d

2. Start Individual Apps:

   # Medusa backend
   cd apps/medusa && pnpm dev
   
   # Storefront
   cd apps/storefront && pnpm dev

3. Stop Services When Done:

   docker compose down

• Database Connection Issues: Ensure Docker containers are running and environment variables match
• Port Conflicts: Check if ports 9000 (Medusa), 3000 (Storefront), 5432 (PostgreSQL), 6379 (Redis) are available
• Missing Dependencies: Run pnpm install in the root directory

Error:

Failed query: select "users"."id", ... "users_sessions"."data" as "sessions" from "users" "users" left join lateral ... from "users_sessions" ...

Cause: Payload CMS authentication is enabled but the required users_sessions table is missing from the database schema.

Solution:

cd apps/storefront
npx payload migrate:create  # Generates migration for missing tables
npx payload migrate         # Applies the migration

This creates the users_sessions table with proper structure and foreign key constraints to the users table.

• storefront: Next.js app integrated with Medusa and PayloadCMS.
• medusa: Medusa backend for ecommerce functionalities.
• studio: drizzle studio for database management.
• email: Email rendering app using react-email and @react-email/components.

• Uses modern React (v19) and Next.js (v15).
• Includes utilities for building, exporting, and type-checking email templates.

• Next Forge
• Medusa Next.js Starter
• PayloadCMS Website template