Aller au contenu principal

🔧 Development Environment Setup Guide

✅ Current System Overview​

1. Complete Auth0 + NextAuth Authentication​

  • ✅ Frontend: NextAuth with Auth0 provider configured
  • ✅ Backend: JWT validation with Auth0 JWKS
  • ✅ Custom Claims: Role-based access control
  • ✅ API Integration: Automatic JWT token injection
  • ✅ TypeScript: Extended session and JWT interfaces

2. Shared Environment Variable System​

  • ✅ Single Source: .env.shared for all Auth0 configuration
  • ✅ Auto-Sync: Environment setup runs before dev commands
  • ✅ NPM Pre-Scripts: Clean, idiomatic npm lifecycle usage
  • ✅ Team-Friendly: Template and automation for consistency

3. Development Workflow Automation​

  • ✅ One Command: npm run dev starts everything
  • ✅ Environment Setup: Automatic before each service
  • ✅ Parallel Services: API, Frontend, and Docs together
  • ✅ Color-Coded Output: Easy to distinguish service logs

🚀 How to Use Your New Setup​

First Time Setup​

# 1. Create your environment file
cp .env.shared.example .env.shared
nano .env.shared  # Add your actual Auth0 values

# 2. Start development
npm run dev

Daily Development​

# Single command starts everything with fresh environment
npm run dev

# This automatically:
# 1. Runs `predev` (./setup-env.sh) - syncs environment
# 2. Runs `dev` - starts API + Frontend + Docs in parallel

Individual Services​

# Start just the API (with environment setup)
npm run dev:api

# Start just the frontend (with environment setup)
npm run dev:frontend

# Start just documentation
npm run dev:docs

🔧 NPM Pre-Script Pattern Benefits​

Why It's Better Than Manual Chaining​

Old Way (Manual):

"dev": "npm run setup-env && npm run start-services"

New Way (NPM Lifecycle):

"predev": "./setup-env.sh",
"dev": "concurrently ..."

Advantages:​

  • ✅ Automatic: NPM handles the execution order
  • ✅ Standard: Industry best practice
  • ✅ Reliable: Proper error handling
  • ✅ Clean: No manual command chaining
  • ✅ Extensible: Easy to add postdev cleanup

📋 Your Complete Script Setup​

{
  "scripts": {
    "setup-env": "./setup-env.sh",

    "predev": "./setup-env.sh",
    "dev": "concurrently --names \"API,FRONTEND,DOCS\" ...",

    "predev:api": "./setup-env.sh",
    "dev:api": "cd apps/api && npm run start:dev",

    "predev:frontend": "./setup-env.sh",
    "dev:frontend": "cd apps/frontend && npm run dev",

    "dev:docs": "cd docs-site && npm run start"
  }
}

🔍 Environment Variable Flow​

1. Shared Configuration (.env.shared)​

AUTH0_CLIENT_ID=abc123
AUTH0_CLIENT_SECRET=secret123
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
NEXTAUTH_SECRET=your-secret
DATABASE_URL=postgresql://...

2. Automatic Distribution​

Frontend (apps/frontend/.env.local):

# NextAuth + Auth0 frontend config
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret
AUTH0_CLIENT_ID=abc123
AUTH0_CLIENT_SECRET=secret123
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
NEXT_PUBLIC_API_URL=http://localhost:3001

Backend (apps/api/.env):

# Auth0 JWT validation + database config
AUTH0_CLIENT_ID=abc123
AUTH0_CLIENT_SECRET=secret123
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
DATABASE_URL=postgresql://...
PORT=3001

🎯 Complete Authentication Flow​

1. User Login​

// Frontend: User clicks login
await signIn("auth0", { callbackUrl: "/protected" });

2. API Requests (Automatic)​

// Frontend: API calls include JWT automatically
const clients = await $api.GET("/clients");
// Request includes: Authorization: Bearer <jwt_token>

3. Backend Validation​

// Backend: Every request validated
@UseGuards(JwtAuthGuard)
@Get()
findAll(@CurrentUser() user: User) {
  // user.role = 'EMTB-ADMIN', 'EMTB-CLIENT', etc.
  return this.service.findAll();
}

📱 Service URLs​

When running npm run dev:

🔐 Security Features​

  • ✅ JWT Validation: Every API request verified with Auth0
  • ✅ Role-Based Access: EMTB-ADMIN, EMTB-LIMITED, EMTB-CLIENT
  • ✅ Custom Claims: Project and organization context
  • ✅ Tenant Isolation: Multi-tenant data filtering ready
  • ✅ Environment Secrets: Gitignored and template-based

🎉 You're All Set!​

Your EMTB project now has:

  1. Production-ready authentication with Auth0 + NextAuth
  2. Automated development workflow with shared environment
  3. Clean, maintainable npm scripts using lifecycle patterns
  4. Complete documentation for team onboarding

Just add your actual Auth0 credentials to .env.shared and run npm run dev! 🚀