---

🚀 NestJS Auth Template

A production-ready NestJS REST API template implementing authentication, security best practices, testing and CI/CD pipeline.

This project is designed as a solid starting point for scalable backend applications.

---

About

This template provides a complete authentication system built with NestJS and Passport strategies.

It includes:

• Google OAuth Authentication
• Email / Password Authentication
• JWT Access Tokens
• Refresh Token Rotation
• Passport Strategies
• Global JWT Auth Guard
• Swagger API Documentation
• Unit Tests
• E2E Tests
• Dedicated test database for E2E tests
• CI/CD Pipeline with GitHub Actions
• Service container database for CI testing
• Husky Git Hooks
• Lint-staged Code Quality
• SWC as the compiler

---

Tech Stack

---

Installation

1. Clone the repository

git clone https://github.com/CarMi0Proggramer/nestjs-auth-template.git

2. Move into the project folder

cd nestjs-auth-template

3. Install dependencies using pnpm

pnpm install

4. Create your environment file from the example:

cp .env.example .env

Then replace the values according to your environment. Example .env:

PORT="3000"
DATABASE_URL="postgresql://user:password@localhost:5432/nest_auth_db"

JWT_SECRET="super_secret_access_token"
JWT_EXPIRES_IN="15m"

REFRESH_JWT_SECRET="super_secret_refresh_token"
REFRESH_JWT_EXPIRES_IN="7d"

GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_SECRET="your_google_client_secret"
GOOGLE_CALLBACK_URL="http://localhost:3000/api/auth/google/callback"

FRONTEND_URL ="http://localhost:5173"

Database Setup

This project uses PostgreSQL. You can use either Neon (cloud) or Docker (local).

Option 1 — Neon Database

Steps:

1. Create a database at: https://neon.tech/
2. Copy your connection string
3. Paste it into .env

Option 2 - PostgreSQL with Docker

Steps:

1. Run a local PostgreSQL container

docker run -d \
--name nest-postgres \
-p 5432:5432 \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=nest_auth_db \
postgres:18

2. Add your connection string

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nest_auth_db

3. Paste it into .env

Running the Application

• Run the development server:

pnpm run dev

• Build the project:

pnpm run build

• Start the production build:

pnpm run start

Testing

• Run unit tests:

pnpm run test

• Run unit tests in watch mode:

pnpm run test:watch

• Generate coverage report::

pnpm run test:cov

End-to-End Tests

• Run e2e tests:

pnpm run test:e2e

• Run e2e tests in watch mode:

pnpm run test:e2e:watch

• Generate e2e coverage:

pnpm run test:e2e:cov

E2E Testing Environment

End-to-end tests run against a dedicated testing database.

• In CI/CD, a temporary PostgreSQL database is created using a service container inside the GitHub Actions workflow.
• In local development, environment variables are loaded from the .env.test file.

This allows tests to run in complete isolation from the development database.

You can configure the test database to use:

• a local PostgreSQL instance
• a cloud database
• or a Docker container

by updating the values in .env.test.

Database Migrations:

• Generate a migration:

pnpm run migration:generate -d ./src/database/data-source.ts ./src/database/migrations/MIGRATION_NAME

• Create a migration:

pnpm run migration:create -d ./src/database/data-source.ts ./src/database/migrations/MIGRATION_NAME

• Run migrations:

pnpm run migration:run

• Rollback last migration:

pnpm run migration:rollback

API Documentation

Swagger documentation will be available at:

http://localhost:3000/api

Once the server is running.

Code Quality

This project includes:

• ESLint
• Prettier
• Husky
• lint-staged

Pre-commit hooks automatically run linting and formatting.

CI/CD

This project includes a GitHub Actions pipeline that runs automatically on:

• push
• pull_request

The pipeline runs:

• unit tests
• e2e tests
• build verification

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a new branch

git checkout -b feature/your-feature

3. Commit your changes using conventional commits syntax
4. Push your branch
5. Open a pull request

License

This project is licensed under MIT License.