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)

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

Quick Start

30 seconds to a running auth API:

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

# Answer 7 quick questions
#  Project name
#  Package manager
#  Database URL
#  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 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
#  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
  src/modules/users/     # User CRUD + profile
  src/modules/health/    # Health check endpoints
 ️  src/common/guards/     # JWT & RBAC guards
  src/common/decorators/ # @Roles(), @Public(), @GetUser()
 ️  prisma/               # Schema + migrations + seed
  test/                  # E2E test suite
  .env                   # Auto-configured
  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

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.

Don't Have PostgreSQL?

Option 1: Local with Docker

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

Option 2: Managed Database

• Supabase - Free PostgreSQL with GUI
• Neon - Serverless Postgres, generous free tier
• Railway - PostgreSQL + deployment
• Render - Free PostgreSQL database

️ Architecture Overview

What's Inside

The generated project follows NestJS best practices:

my-app/
  src/
     modules/auth/
       auth.controller.ts      # Login, signup, refresh, logout
       auth.service.ts         # JWT logic, token rotation
       strategies/             # JWT strategies
   
     modules/users/
       users.controller.ts     # CRUD endpoints
       users.service.ts        # User business logic
       dto/                    # Data transfer objects
   
     modules/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

 ️ prisma/
    schema.prisma               # Database models
    seed.ts                     # Default admin user
    migrations/                 # Version-controlled DB changes

  test/
    app.e2e-spec.ts            # End-to-end tests
    jest-e2e.json              # Test configuration

  Config Files
     .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
• Prisma - Type-safe database access

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

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
• Interactive Setup Guide
• Quick Reference
• Changelog

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 with ️ by Sabin Shrestha

Sponsors & Supporters

Your support keeps this project maintained and improved

---

_{Generated projects follow NestJS best practices and OWASP security guidelines
1.1.0 Updated November 2025 MIT License}

**Now go build something amazing! **