Node Hybrid JWT + Session Auth API

This is a backend API that uses a hybrid authentication approach combining Express server-side sessions and JWT-based access control, with all credentials stored in HTTP-only cookies. This approach ensures security while allowing stateless validation for route access.

Setup

---

Follow these steps to get the project up and running with Prisma and ensure the prisma/generated folder is created properly.

1. Environment Configuration To run the application locally, create a .env file in the root directory with the following variables:

   # PostgreSQL connection string
   DATABASE_URL=postgresql://admin_pg:password@localhost:5433/local-express-hybrid-auth-api-db
   
   # Google OAuth configuration
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
   
   # GitHub OAuth configuration
   GITHUB_CLIENT_ID=your-github-client-id
   GITHUB_CLIENT_SECRET=your-github-client-secret
   GITHUB_CALLBACK_URL=http://localhost:3000/auth/github/callback

2. Install Dependencies: Install all required dependencies for the project.

   npm install

3. Generate Prisma Client and Artifacts: Prisma generates the database client and optionally other files (like types or codegen outputs) into the prisma/generated folder. To generate everything:

   npx prisma generate

   This command reads your schema.prisma file and creates the necessary output in node_modules/.prisma and (if configured) in prisma/generated. Re-run this command any time you modify your Prisma schema.

4. Apply Database Migrations: If you're using Prisma Migrate and have migrations defined, run:

   npx prisma migrate dev

   This will:

   • Apply all pending migrations to your local database
   • Generate the Prisma Client
   • Optionally run seed scripts if configured

5. Open Prisma Studio (Optional): Prisma Studio is a visual interface to explore and manipulate your database during development.

   npx prisma studio

   This opens a browser window where you can browse tables, add records, and debug data visually.

Notes:

• If your project is configured to use the prisma/generated folder (e.g., for custom types or GraphQL artifacts), it will be populated by npx prisma generate. This folder is typically auto-generated and should either be:

  • Ignored in version control (.gitignore), or
  • Re-generated by every contributor using the steps above. Do not manually edit files in prisma/generated unless explicitly intended.

• You can generate a strong SESSION_SECRET using the following command in your terminal (Unix/macOS/Linux):openssl rand -base64 64. On windows you can use git bash. Then add it to your .env file for production use:

  SESSION_SECRET=your_generated_value_here
  

Email Development with MinIO/CDN

---

This project uses MinIO as a local S3-compatible object storage service for serving static assets (logos, images) used in email templates during development. This setup provides a seamless development experience while maintaining production-ready patterns.

What is MinIO?

MinIO is a high-performance, S3-compatible object storage server that provides:

• S3-compatible API: Works with existing S3 tools and libraries
• Local Development: Runs in Docker containers for isolated development
• Public Asset Serving: Serves static files via HTTP URLs
• Headless Operation: Runs without a web interface for automated workflows

How It Works

Development Mode

When running npm run email:dev, the system:

1. Starts MinIO Container: Launches a local MinIO server on port 9000
2. Creates Public Bucket: Sets up a public-assets bucket with public read access
3. Uploads Assets: Copies static assets from .devcontainer/cdn-assets/ to MinIO
4. Serves Assets: Assets become available at http://localhost:9000/public-assets/
5. Runs React Email: Starts the email preview server with access to CDN assets

Asset Structure

.devcontainer/cdn-assets/
├── static/
│   ├── logo.png          # Company logo
│   ├── header.png        # Email header image
│   ├── footer.png        # Email footer image
│   └── logo-placeholder.png
├── email-header.jpg      # Legacy header image
├── email-footer.png      # Legacy footer image
└── company-icon.svg      # Company icon

Environment Configuration

The CDN_URL environment variable controls asset URLs:

# Development (MinIO)
CDN_URL=http://localhost:9000/public-assets

# Production (CDN)
CDN_URL=https://cdn.yourdomain.com/assets

Production Deployment

Replacing MinIO with a CDN

In production, MinIO is replaced with a Content Delivery Network (CDN) for better performance and global distribution:

Option 1: Cloud Storage + CDN

# AWS S3 + CloudFront
CDN_URL=https://d1234567890.cloudfront.net/assets

# Google Cloud Storage + CDN
CDN_URL=https://storage.googleapis.com/your-bucket/assets

# Azure Blob Storage + CDN
CDN_URL=https://your-cdn.azureedge.net/assets

Option 2: Dedicated CDN Services

# Cloudflare
CDN_URL=https://assets.yourdomain.com

# KeyCDN
CDN_URL=https://your-zone.kxcdn.com/assets

# BunnyCDN
CDN_URL=https://your-zone.b-cdn.net/assets

Migration Steps

1. Upload Assets: Copy all files from .devcontainer/cdn-assets/ to your CDN
2. Update Environment: Change CDN_URL in production environment files
3. Test URLs: Verify all asset URLs are accessible
4. Update Email Templates: Ensure all Img components use ${assetsUrl}

Benefits of CDN in Production

• Global Distribution: Faster loading times worldwide
• Caching: Reduced server load and bandwidth costs
• HTTPS: Secure asset delivery
• Scalability: Handles high traffic volumes
• Reliability: Multiple edge locations for redundancy

Email Development Workflow

Starting Email Development

# Start MinIO + React Email preview
npm run email:dev

# Access email preview
open http://localhost:3000

Adding New Assets

1. Add files to .devcontainer/cdn-assets/static/
2. Restart npm run email:dev to upload new assets
3. Reference in email templates: ${assetsUrl}/static/filename.png

Stopping Services

# Stop MinIO containers
npm run email:stop

Troubleshooting

MinIO Not Starting

• Check if port 9000 is available
• Verify Docker is running
• Check container logs: docker logs email-minio

Assets Not Loading

• Verify MinIO is running: curl http://localhost:9000/minio/health/live
• Check bucket exists: curl http://localhost:9000/public-assets/
• Verify asset upload: curl http://localhost:9000/public-assets/static/logo.png

Translation Errors

• Ensure translation files exist in src/locales/en/translation.json
• Check email template imports are correct
• Verify getEmailTranslator() function is working

Resources

---

• Lucia Auth This website provides valuable resources for understanding and implementing authentication in JavaScript and TypeScript. Special thanks to pilcrowonpaper for the clear and well-documented content.
• How To Set Up a Node Project With Typescript
• How to Setup a TypeScript + Node.js Project
• Creating a basic REST API with TypeScript, Node.js, Swagger MVC
• OpenAPI React Query Codegen