npx create-nestjs-auth@latest

Why This Exists

Building secure JWT authentication isn't trivial. You need:

• Access tokens + refresh token rotation
• HttpOnly cookies (not localStorage)
• Multi-device session management
• Role-based access control (RBAC)
• Rate limiting & brute-force protection
• PII-safe logging
• Proper password hashing (bcrypt 12 rounds)
• Flexible ORM & database choices

This CLI gives you all of that. Production-ready, security-hardened, tested patterns - instantly.

Quick Start

30 seconds to a running auth API:

# Run the CLI
npx create-nestjs-auth@latest

# Answer quick questions
#  Project name
#  ORM (Prisma, Drizzle, TypeORM, or Mongoose)
#  Database (PostgreSQL, MySQL, SQLite, or MongoDB)
#  Package manager
#  Install dependencies
#  Setup database
#  Initialize git

# Done! Your API is running at http://localhost:8080/api/v1

That's it. No configuration files. No secret management headaches. No database setup confusion.

create-nestjs-auth

? What is your project name? my-awesome-api
? Which ORM would you like to use? Prisma
? Which database would you like to use? PostgreSQL
? Which package manager? pnpm (detected)
? Install dependencies? Yes
? Initialize git repository? Yes

 Creating my-awesome-api...
 Installing dependencies...
 Success! Created my-awesome-api

? Complete setup now? Yes
 Generating JWT secrets...
? Enter PostgreSQL URL: postgresql://localhost:5432/mydb
? Set up database now? Yes
 Running migrations & seed...
 Default admin: admin@example.com / Admin@123

? Start dev server? Yes
 Server running at http://localhost:8080/api/v1

What You Get

See It in Action

Video Demo (Coming Soon)

We're creating a video walkthrough. Subscribe to discussions to get notified!

60-Second Complete Setup

# 1. Create project (10 seconds)
npx create-nestjs-auth@latest my-api

# 2. Answer prompts (20 seconds)
#  Project name: my-api
#  ORM: Prisma (or Drizzle, TypeORM, Mongoose)
#  Database: PostgreSQL (or MySQL, SQLite, MongoDB)
#  Package manager: pnpm
#  Install dependencies: Yes
#  Database URL: postgresql://localhost:5432/mydb
#  Setup database: Yes
#  Start server: Yes

# 3. Your API is live! (30 seconds)
#  http://localhost:8080/api/v1

Live Example

# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"admin@example.com","password":"Admin@123"}'

# Response:
{
  "user": {
    "id": "cm3k5j8l9...",
    "email": "admin@example.com",
    "fullName": "Admin User",
    "role": "ADMIN"
  }
}

# Access protected route
curl http://localhost:8080/api/v1/auth/me -b cookies.txt

# Response:
{
  "id": "cm3k5j8l9...",
  "email": "admin@example.com",
  "role": "ADMIN",
  "isActive": true
}

What the Code Looks Like

Adding a protected admin endpoint (2 lines):

@Roles(UserRole.ADMIN)  //  Just add this decorator
@Delete('posts/:id')
deletePost() {
  return { message: 'Deleted' };
}

Getting the current user (1 line):

@Get('my-profile')
getProfile(@GetUser() user) {  //  User automatically injected
  return { profile: user };
}

Making an endpoint public (1 line):

@Public()  //  Skip authentication
@Get('posts')
findAll() {
  return { posts: [] };
}

That's it. No boilerplate. No configuration. Just decorators.

How It Works

The Magic Behind the CLI

graph LR
    A[Run CLI] --> B[Interactive Setup]
    B --> C[Generate Project]
    C --> D[Install Dependencies]
    D --> E[Generate JWT Secrets]
    E --> F[Configure Database]
    F --> G[Run Migrations]
    G --> H[Seed Admin User]
    H --> I[Start Dev Server]
    
    style A fill:#667eea
    style I fill:#48bb78

What Gets Created

my-app/
├── src/
│   ├── modules/
│   │   ├── auth/          # JWT + Refresh token logic
│   │   ├── users/         # User CRUD + profile
│   │   └── health/        # Health check endpoints
│   ├── common/
│   │   ├── guards/        # JWT & RBAC guards
│   │   ├── decorators/    # @Roles(), @Public(), @GetUser()
│   │   └── filters/       # Exception handling
│   └── config/            # Environment & logging config
├── prisma/                # (Prisma) Schema + migrations + seed
├── drizzle/               # (Drizzle) Schema + migrations
├── test/                  # E2E test suite
├── .env                   # Auto-configured secrets
└── package.json           # All dependencies ready

Usage Examples

1. Interactive Mode (Recommended)

Zero configuration. Just answer questions:

npx create-nestjs-auth@latest

The CLI guides you through:

1. Project name
2. Package manager (auto-detected)
3. Dependency installation
4. Git initialization
5. JWT secret generation
6. Database configuration
7. Database setup (migrations + seed)
8. Dev server launch

Perfect for: First-time users, learning, rapid prototyping

2. Quick Mode

Fastest way to get started:

npx create-nestjs-auth@latest my-app
cd my-app
# Edit .env with your database URL
npm run prisma:generate && npm run prisma:migrate && npm start:dev

Perfect for: Experienced users who know the drill

3. Automation Mode

For CI/CD and scripts:

# Skip all prompts, use defaults
npx create-nestjs-auth@latest my-app --yes

# Custom package manager
npx create-nestjs-auth@latest my-app --package-manager pnpm

# Skip dependency installation
npx create-nestjs-auth@latest my-app --skip-install

# Skip git initialization
npx create-nestjs-auth@latest my-app --skip-git

# Combine options
npx create-nestjs-auth@latest my-app --yes --skip-git --package-manager bun

# Specify ORM and database
npx create-nestjs-auth@latest my-app --orm drizzle --database postgres --yes

# MongoDB with Mongoose
npx create-nestjs-auth@latest my-app --orm mongoose --yes

Perfect for: CI/CD pipelines, automation scripts, Docker builds

Complete API Reference

Your generated API includes these endpoints out of the box:

Authentication

Users (Admin Only)

Profile

Health Checks

# 1. Login and save cookies
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"admin@example.com","password":"Admin@123"}'

# Response:
# {
#   "user": {
#     "id": "cm3k5j8l9...",
#     "email": "admin@example.com",
#     "role": "ADMIN"
#   }
# }

# 2. Access protected route (uses cookies)
curl http://localhost:8080/api/v1/auth/me -b cookies.txt

# 3. List all users (admin only)
curl http://localhost:8080/api/v1/users -b cookies.txt

# 4. Refresh your token
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -b cookies.txt \
  -c cookies.txt

# 5. Logout
curl -X POST http://localhost:8080/api/v1/auth/logout -b cookies.txt

import { Controller, Get } from '@nestjs/common';
import { Roles } from '@/common/decorators/roles.decorator';
import { UserRole } from '@prisma/client';

@Controller('posts')
export class PostsController {
  // Public endpoint - anyone can access
  @Public()
  @Get()
  findAll() {
    return { posts: [] };
  }

  // Protected endpoint - any authenticated user
  @Get('my-posts')
  getMyPosts(@GetUser() user) {
    return { posts: [], userId: user.id };
  }

  // Admin only - requires ADMIN role
  @Roles(UserRole.ADMIN)
  @Delete(':id')
  deletePost() {
    return { message: 'Post deleted' };
  }
}

CLI Options Reference

System Requirements

Note: The CLI automatically checks your Node.js version before proceeding.

Database Setup Options

PostgreSQL (Local with Docker)

docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16

MySQL (Local with Docker)

docker run --name mysql -e MYSQL_ROOT_PASSWORD=mysql -p 3306:3306 -d mysql:8

MongoDB (Local with Docker)

docker run --name mongodb -p 27017:27017 -d mongo:6

SQLite No setup needed! SQLite creates a local file automatically.

Managed Database Services

• Supabase - Free PostgreSQL with GUI
• Neon - Serverless Postgres, generous free tier
• PlanetScale - Serverless MySQL
• MongoDB Atlas - Free MongoDB cluster
• Railway - PostgreSQL/MySQL + deployment
• Render - Free PostgreSQL database

ORM & Database Options

Choose the combination that fits your project:

Supported ORMs

Supported Databases

ORM + Database Compatibility

┌─────────────┬────────────┬───────┬────────┬─────────┐
│             │ PostgreSQL │ MySQL │ SQLite │ MongoDB │
├─────────────┼────────────┼───────┼────────┼─────────┤
│ Prisma      │     ✅     │  ✅   │   ✅   │   ❌    │
│ Drizzle     │     ✅     │  ✅   │   ✅   │   ❌    │
│ TypeORM     │     ✅     │  ✅   │   ✅   │   ❌    │
│ Mongoose    │     ❌     │  ❌   │   ❌   │   ✅    │
└─────────────┴────────────┴───────┴────────┴─────────┘

Which Should I Choose?

Choose Prisma if:

• You want the best developer experience
• You're new to ORMs
• You want visual database management (Prisma Studio)

Choose Drizzle if:

• You prefer writing SQL-like code
• You want a lightweight solution
• Performance is critical

Choose TypeORM if:

• You're familiar with decorators
• You need Active Record pattern
• You're migrating from other languages (Java, C#)

Choose Mongoose if:

• You're using MongoDB
• You need flexible schemas
• You want document validation

Architecture Overview

What's Inside

The generated project follows NestJS best practices with a modular architecture:

my-app/
├── src/
│   ├── modules/
│   │   ├── auth/
│   │   │   ├── auth.controller.ts      # Login, signup, refresh, logout
│   │   │   ├── auth.service.ts         # JWT logic, token rotation
│   │   │   └── auth.module.ts
│   │   │
│   │   ├── users/
│   │   │   ├── users.controller.ts     # CRUD endpoints
│   │   │   ├── users.service.ts        # User business logic
│   │   │   └── dto/                    # Data transfer objects
│   │   │
│   │   └── health/
│   │       └── health.controller.ts    # K8s-ready health checks
│   │
│   ├── common/
│   │   ├── decorators/             # @Roles(), @Public(), @GetUser()
│   │   ├── guards/                 # JWT + RBAC guards
│   │   ├── interceptors/           # Response formatting
│   │   ├── filters/                # Exception handling
│   │   └── validators/             # Custom validation rules
│   │
│   ├── config/
│   │   ├── config.module.ts        # Environment config
│   │   ├── env.validation.ts       # Zod validation
│   │   └── logger.config.ts        # Pino logger setup
│   │
│   └── database/                   # ORM-specific setup
│       # Prisma:   prisma.service.ts, prisma.module.ts
│       # Drizzle:  drizzle.ts, schema.ts, database.module.ts
│       # TypeORM:  entities/, database.module.ts
│       # Mongoose: schemas/, database.module.ts
│
├── prisma/ (if using Prisma)
│   ├── schema.prisma               # Database models
│   ├── seed.ts                     # Default admin user
│   └── migrations/                 # Version-controlled DB changes
│
├── drizzle/ (if using Drizzle)
│   ├── drizzle.config.ts           # Drizzle configuration
│   └── migrations/                 # SQL migrations
│
├── test/
│   ├── app.e2e-spec.ts             # End-to-end tests
│   └── jest-e2e.json               # Test configuration
│
├── .env                            # Your secrets (auto-generated)
├── .env.example                    # Template for team
├── nest-cli.json                   # NestJS config
├── tsconfig.json                   # TypeScript config
└── eslint.config.mjs               # Linting rules

Key Design Patterns

• Guards - JWT validation + RBAC on every route
• Interceptors - Transform responses, add metadata
• Decorators - Clean syntax for auth requirements
• DTOs - Type-safe request validation
• ORM Agnostic - Same API regardless of database choice

Common Use Cases

1. Add a New Protected Endpoint

// src/modules/posts/posts.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';
import { Roles } from '@/common/decorators/roles.decorator';
import { GetUser } from '@/common/decorators/get-user.decorator';
import { UserRole } from '@prisma/client';

@Controller('posts')
export class PostsController {
  // Anyone can view posts
  @Public()
  @Get()
  findAll() {
    return { posts: [] };
  }

  // Authenticated users can create posts
  @Post()
  create(@GetUser() user, @Body() createPostDto) {
    return { post: { authorId: user.id, ...createPostDto } };
  }

  // Only admins can delete posts
  @Roles(UserRole.ADMIN)
  @Delete(':id')
  remove(@Param('id') id: string) {
    return { message: 'Post deleted' };
  }
}

2. Add a New User Role

// 1. Update prisma/schema.prisma
enum UserRole {
  USER
  ADMIN
  MODERATOR  //  Add new role
}

// 2. Run migration
npm run prisma:migrate

// 3. Use it in your code
@Roles(UserRole.MODERATOR)
@Patch('posts/:id')
moderatePost() { }

3. Customize JWT Token Expiry

# .env
JWT_ACCESS_EXPIRY=15m     # Short-lived access token
JWT_REFRESH_EXPIRY=7d     # Refresh every week

4. Add Email Verification

// Add field to User model
model User {
  emailVerified DateTime?
  verificationToken String?
}

// Add verification endpoint
@Post('verify-email')
async verifyEmail(@Body() dto: VerifyEmailDto) {
  // Your logic here
}

5. Deploy to Production

# Build for production
npm run build

# Run production server
npm run start:prod

# Or use Docker (Dockerfile included)
docker build -t my-app .
docker run -p 8080:8080 my-app

Security Features Explained

1. Token Rotation

Every time you refresh your access token, the old refresh token is invalidated. If someone steals your refresh token, they can only use it once.

// Automatic in generated code
async refresh(token: string) {
  // 1. Validate old token
  // 2. Generate NEW tokens
  // 3. Invalidate OLD refresh token
  // 4. Return new tokens
}

2. HttpOnly Cookies (No XSS)

Tokens are stored in HttpOnly cookies that JavaScript can't access. Even if malicious JS runs on your site, it can't steal tokens.

// Set in response automatically
res.cookie('accessToken', token, {
  httpOnly: true,     // JS can't read
  secure: true,       // HTTPS only
  sameSite: 'strict'  // CSRF protection
});

3. Bcrypt 12 Rounds

Passwords are hashed with bcrypt using 12 rounds (2025 security baseline). Each password takes ~250ms to hash, making brute-force attacks impractical.

// Automatic in generated code
const hashedPassword = await bcrypt.hash(password, 12);

4. Rate Limiting

• 5 attempts/minute on auth endpoints
• 10 requests/minute globally per IP
• Prevents brute-force attacks

5. PII-Safe Logging

Passwords and tokens are automatically redacted from logs:

// What gets logged:
{"level":30,"msg":"POST /auth/login","email":"[REDACTED]","password":"[REDACTED]"}

// Not this:
{"email":"user@example.com","password":"SecurePass123"}

Comparison with Alternatives

vs. Building from Scratch

vs. NestJS Official Auth Template

vs. Third-Party Auth (Auth0, Firebase)

Why Not Just Use Passport?

Passport is great, but it's just one piece of the puzzle. You still need:

• Database models and migrations
• Refresh token rotation logic
• RBAC guards and decorators
• Rate limiting
• Cookie management
• PII-safe logging
• Testing setup

create-nestjs-auth gives you all of this, integrated and tested together.

Troubleshooting

npx create-nestjs-auth@latest my-app

npm install -g create-nestjs-auth
create-nestjs-auth my-app

npm uninstall -g create-nestjs-auth
npm cache clean --force
npm install -g create-nestjs-auth

# Using nvm (recommended)
nvm install 20
nvm use 20

# Or download from nodejs.org

# Check if PostgreSQL is running
pg_isready

# Or test connection
psql postgresql://user:password@localhost:5432/mydb

openssl rand -base64 32
# Update JWT_ACCESS_SECRET in .env

openssl rand -base64 32
# Update JWT_REFRESH_SECRET in .env

npm run start:dev

PORT=3000

# Linux/Mac
lsof -ti:8080 | xargs kill -9

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess | Stop-Process

# Single origin
CORS_ORIGIN=http://localhost:3000

# Multiple origins
CORS_ORIGIN=http://localhost:3000,http://localhost:5173

npm run prisma:generate

rm -rf node_modules
npm install
npm run prisma:generate

npm run drizzle:generate
npm run drizzle:migrate

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

npm run typeorm:migration:run

DATABASE_URL=mongodb://localhost:27017/mydb

Contributing

We love contributions! Here's how you can help:

Found a Bug?

1. Check if it's already reported in Issues
2. If not, open a new issue with:
   • Clear title
   • Steps to reproduce
   • Expected vs actual behavior
   • Your environment (Node version, OS, etc.)

Have an Idea?

1. Open a Discussion
2. Describe your idea and use case
3. Get feedback from the community

Want to Contribute Code?

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly: npm test
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Showcase

Built something amazing with this CLI? We'd love to feature your project!

Projects Using create-nestjs-auth

Success Stories

"Saved me 2 weeks of setup time. The security patterns alone are worth it."
Developer building a SaaS platform

"Perfect starter for our microservices. Clean code, great documentation."
CTO at a tech startup

"Used it for my university project. Got an A+ and learned best practices."
Student learning backend development

Share your story: Open a discussion

Tech Stack

Links & Resources

Documentation

• Full Template Documentation
• Contributing Guide - How to contribute
• Security Policy - Reporting vulnerabilities
• Changelog - Version history

Community

• GitHub Discussions - Ask questions, share ideas
• Report Issues - Found a bug? Let us know
• View Changelog - See what's new

Learning Resources

• NestJS Documentation
• Prisma Documentation
• JWT.io - Learn about JWT tokens
• OWASP Top 10 - Web security basics

Related Projects

• create-next-app - Create Next.js apps
• create-t3-app - Full-stack TypeScript
• nest-cli - Official NestJS CLI

FAQ

npm publish --access public

cd apps/backend
npx create-nestjs-auth@latest api

Acknowledgments

This project wouldn't exist without these amazing technologies:

• NestJS - The progressive Node.js framework
• Prisma - Next-generation database toolkit
• PostgreSQL - World's most advanced open source database

Special thanks to the open-source community for feedback and contributions!

License

MIT License - do whatever you want with it!

See LICENSE for full details.

Copyright (c) 2025 Sabin Shrestha

---

Before You Go...

Did this save you time?

Star this repository to help others discover it!

Share with your network

Help other developers save 40 hours of work:

Contribute

Found a bug? Have a feature idea? Open an issue or submit a PR!

---

Built by Sabin Shrestha

Sponsors & Supporters

Your support keeps this project maintained and improved

---

_{Generated projects follow NestJS best practices and OWASP security guidelines
v2.0.8 | Multi-ORM & Multi-Database Support | December 2025 | MIT License}

Now go build something amazing!