![\"npm](\"https://img.shields.io/npm/v/@dylantovar/nestjs-auth-kit?color=E0234E&label=npm&logo=npm\")
\n ![\"Node.js\"](\"https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white\"){kind=icon}
\n ![\"NestJS\"](\"https://img.shields.io/badge/NestJS-%3E%3D10-E0234E?logo=nestjs&logoColor=white\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
\n\n
\n CLI scaffolder that generates a complete authentication module inside an existing NestJS project.
\n No manual wiring required.\n
\n Installation ·\n Usage ·\n What it generates ·\n Post-install ·\n Local development\n
\n\n---\n\n## Installation\n\nFrom the **root of your NestJS project**:\n\n```bash\n# No global install required (recommended)\npnpm dlx @dylantovar/nestjs-auth-kit init\n\n# With npx\nnpx @dylantovar/nestjs-auth-kit init\n\n# Global\npnpm add -g @dylantovar/nestjs-auth-kit && nestjs-auth-kit init\n```\n\n**Requirements**\n\n- Node.js ≥ 18\n- NestJS project with an existing `src/app.module.ts`\n- PostgreSQL or any TypeORM-compatible database\n\n---\n\n## Interactive flow\n\nThe CLI asks up to 7 questions and adapts the output to your answers:\n\n```\n? Which ORM are you using?\n ❯ TypeORM\n Prisma (Coming soon)\n\n? Which JWT strategy do you want to implement?\n ❯ Access + Refresh token rotation\n Access token only\n\n? Add Role-Based Access Control (RBAC)?\n ❯ Yes\n\n? Which roles will your system have?\n default: ADMIN, USER\n\n? Add rate limiting to login endpoints?\n ❯ Yes\n\n? Which storage backend for rate limiting?\n ❯ In-Memory\n Redis\n\n? Generate a docker-compose.yml for DB (and Redis if applicable)?\n ❯ Yes\n```\n\nWhen finished, the CLI prints the exact dependency install command for your configuration and points to the `README-AUTH.md` generated in your project.\n\n---\n\n## What it generates\n\n```text\nyour-nestjs-project/\n├── .env.example # Environment variable reference\n├── README-AUTH.md # Step-by-step integration guide\n├── docker-compose.yml # ← optional (PostgreSQL + Redis)\n│\n└── src/\n ├── config/\n │ ├── configuration.ts # Typed env config\n │ ├── env.validation.ts # Joi validation on boot\n │ └── database.config.ts # TypeORM + DataSource for migrations\n │\n └── modules/\n └── auth/\n ├── auth.module.ts\n ├── auth.controller.ts\n ├── auth.service.ts\n ├── account.entity.ts\n ├── refresh-token.entity.ts # ← Access + Refresh only\n ├── dto/\n │ ├── login.dto.ts\n │ ├── register.dto.ts\n │ └── refresh-token.dto.ts # ← Access + Refresh only\n ├── enums/\n │ └── role.enum.ts # ← RBAC only\n ├── guards/\n │ ├── jwt-auth.guard.ts\n │ └── roles.guard.ts # ← RBAC only\n ├── decorators/\n │ ├── current-user.decorator.ts\n │ └── roles.decorator.ts # ← RBAC only\n └── strategies/\n ├── jwt.strategy.ts\n └── jwt-refresh.strategy.ts # ← Access + Refresh only\n```\n\n### Endpoints\n\n| Method | Path | Auth | Notes |\n| ------ | ---------------- | ------------- | ---------------------------------- |\n| `POST` | `/auth/register` | — | Creates account |\n| `POST` | `/auth/login` | — | Rate limited if enabled |\n| `POST` | `/auth/refresh` | Refresh token | Access + Refresh only |\n| `POST` | `/auth/logout` | JWT / Refresh | Revokes token if applicable |\n| `POST` | `/auth/me` | JWT | Returns authenticated user payload |\n\n---\n\n## Features\n\n| Feature | Description |\n| ------------------------ | ------------------------------------------------------------------------ |\n| **Interactive CLI** | Dynamic prompts; output adapts to your choices |\n| **TypeORM + PostgreSQL** | Entities, DB config and DataSource for migrations _(Prisma on roadmap)_ |\n| **Flexible JWT** | Access token only or Access + Refresh with rotation and DB revocation |\n| **RBAC** | Custom roles at setup, `@Roles()` decorator and exported `RolesGuard` |\n| **Rate limiting** | `@nestjs/throttler` on login — In-Memory or distributed Redis |\n| **Docker Compose** | PostgreSQL + Redis optional; does not overwrite an existing compose file |\n| **Typed config** | `configuration.ts` + Joi validation on startup |\n| **`.env.example`** | Auto-generated with variables based on your configuration |\n| **`README-AUTH.md`** | Integration guide with curl examples, Docker steps and RBAC example |\n\n### Production-grade practices\n\nThe generated code is not a tutorial snippet:\n\n- `bcrypt` with `saltRounds: 12`\n- Refresh token rotation — every refresh revokes the previous token and issues a new one\n- DB revocation with `revokedAt` (records are marked, not deleted)\n- Uniform `INVALID_CREDENTIALS` error — does not reveal whether the email exists or the password is wrong\n- DTOs with `class-validator` and `@Transform` for input normalization\n\n---\n\n## Configuration options\n\n### JWT: Access + Refresh vs Access token only\n\n| | Access token only | Access + Refresh |\n| ----------------- | ----------------------- | ------------------------------------ |\n| Complexity | Minimal | Full |\n| Expiry | Long-lived token (~24h) | Short access (~15min) + long refresh |\n| Remote revocation | No | Yes — `revokedAt` in DB |\n| Best for | Internal APIs, MVPs | SaaS, mobile apps, production |\n\n### Rate limiting: In-Memory vs Redis\n\n| | In-Memory | Redis |\n| -------- | -------------------------- | ---------------------------------- |\n| Setup | Zero extra config | Requires Redis |\n| Scaling | Single instance | Multiple instances + load balancer |\n| Best for | Single server, development | Horizontal production |\n\n`ThrottlerGuard` is registered as `APP_GUARD` inside `AuthModule` — it applies to the entire app once you import `AuthModule`. Default limits: **5 req/min** on `/auth/login`, **10 req/min** everywhere else.\n\nTo exclude routes use `@SkipThrottle()`:\n\n```typescript\nimport { SkipThrottle } from '@nestjs/throttler';\n\n@Get('health')\n@SkipThrottle()\ncheck() { return { status: 'ok' }; }\n```\n\n---\n\n## Environment variables\n\nThe CLI generates `.env.example`. Copy it and fill in your values:\n\n```bash\ncp .env.example .env\n```\n\n```env\nNODE_ENV=development\nPORT=3000\nAPP_URL=http://localhost:3000\nFRONTEND_URL=http://localhost:3001\n\n# JWT — minimum 32 characters (validated on startup)\nJWT_ACCESS_SECRET=change_me_to_a_secret_with_at_least_32_chars\nJWT_ACCESS_EXPIRES=15m\n\n# Access + Refresh only\nJWT_REFRESH_SECRET=another_secret_with_at_least_32_characters\nJWT_REFRESH_EXPIRES=7d\n\n# Database\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=postgres\nDB_PASSWORD=postgres\nDB_NAME=postgres\n\n# Rate limiting + Redis only\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_PASSWORD=change_me\n```\n\n---\n\n## Post-install checklist\n\n```bash\n# 1. Install dependencies (the CLI prints the exact command when it finishes)\npnpm add @nestjs/passport passport passport-jwt @nestjs/jwt ...\n\n# 2. Set up environment variables\ncp .env.example .env\n\n# 3. Import AuthModule and ConfigModule in app.module.ts\n\n# 4. Start the database\ndocker compose up -d\n\n# 5. Create the auth schema in PostgreSQL\ndocker compose exec postgres psql -U postgres -d postgres -c \"CREATE SCHEMA auth;\"\n\n# 6. Run migrations\npnpm typeorm migration:run\n\n# 7. Test\ncurl -X POST http://localhost:3000/auth/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\":\"test@example.com\",\"password\":\"password123\"}'\n```\n\n> Steps 3–7 are detailed with full code in the **`README-AUTH.md`** generated in your project.\n\n---\n\n## Local development\n\n```bash\ngit clone https://github.com/dylantovar/nestjs-auth-kit.git\ncd nestjs-auth-kit\npnpm install\npnpm build\n\n# Test against a clean NestJS project\ncd /path/to/your-nestjs-project\nnode /path/to/nestjs-auth-kit/dist/index.js init\n```\n\n### CLI stack\n\n| Dependency | Role |\n| ----------- | ------------------- |\n| `commander` | Command parsing |\n| `inquirer` | Interactive prompts |\n| `ejs` | Template engine |\n| `chalk` | Colored output |\n| `ora` | Loading spinners |\n| `fs-extra` | File writing |\n\n### Repository structure\n\n```text\nnestjs-auth-kit/\n├── src/\n│ ├── index.ts\n│ ├── commands/init.ts\n│ ├── prompts/questions.ts\n│ ├── generators/\n│ │ ├── template.renderer.ts # Shared EJS engine\n│ │ ├── config.generator.ts # src/config/* + .env.example\n│ │ ├── auth.generator.ts # src/modules/auth/*\n│ │ └── docker.generator.ts # docker-compose.yml\n│ └── templates/\n│ ├── config/\n│ ├── docker/\n│ ├── dto/\n│ ├── guards/\n│ ├── decorators/\n│ ├── strategies/\n│ ├── enums/\n│ └── orm/typeorm/\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## Roadmap\n\n- [x] TypeORM + PostgreSQL\n- [x] JWT Access + Refresh with rotation and revocation\n- [x] RBAC with custom roles\n- [x] Rate limiting (In-Memory / Redis)\n- [x] Docker Compose\n- [x] `.env.example` + Joi validation\n- [ ] Prisma support\n- [ ] Automatic `app.module.ts` modifiers\n- [ ] Generation tests + CI\n- [ ] npm publish\n\n---\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","homepage":"https://github.com/dylan-tovar/nestjs-auth-kit#readme","bugs":{"url":"https://github.com/dylan-tovar/nestjs-auth-kit/issues"}}