# brocoders/nestjs-boilerplate: NestJS REST API Boilerplate with TypeORM and Mongoose

> brocoders/nestjs-boilerplate is a TypeScript NestJS REST API starter that ships two database configurations (Postgres with TypeORM, MongoDB with Mongoose), built-in authentication with social login, I18N, file uploads, Swagger documentation, and Docker compose setup from a single repository.

**brocoders/nestjs-boilerplate** — NestJS boilerplate. Auth, TypeORM, Mongoose, Postgres, MongoDB, Mailing, I18N, Docker.

- Repository: https://github.com/brocoders/nestjs-boilerplate
- Website: https://nestjs-boilerplate-test.herokuapp.com/docs
- Stars: 4,408 · Forks: 961
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/brocoders-nestjs-boilerplate

## What brocoders/nestjs-boilerplate Provides and Who Uses It

Starting a production-ready NestJS API from scratch requires wiring together authentication, database connection, migrations, mailing, file uploads, internationalization, API documentation, and testing before any domain logic is written. This boilerplate provides all of those pre-configured in a single repository. The target user is a team that has chosen NestJS and TypeScript for a new REST API project and wants a consistent, tested foundation rather than assembling these layers individually.

The boilerplate is version 1.2.0 and belongs to the Brocoders bc boilerplates ecosystem, which also includes a compatible frontend at extensive-react-boilerplate. A live demo of the Swagger documentation is available at the Heroku URL listed in the README. The repository uses Renovate for automatic dependency updates and Husky for pre-commit hooks, which means incoming dependency pull requests arrive automatically.

## Two Database Modes: Postgres with TypeORM and MongoDB with Mongoose

The repository supports two distinct database configurations. The relational mode connects to PostgreSQL via TypeORM. The document mode connects to MongoDB via Mongoose. The two modes are not interchangeable at runtime: each has its own startup script, its own Docker Compose configuration, its own environment file, and its own generator commands.

The Docker Compose file for the relational mode starts a postgres:17.9-alpine container alongside a Maildev mail-catching service, an Adminer database browser on port 8080, and the API container. The environment file env-example-relational contains the Postgres connection variables. The env-example-document file covers the MongoDB variant. Copy the relevant example file to .env before running.

The TypeORM migration scripts are exposed through npm: `migration:generate` creates a new migration file, `migration:run` applies pending migrations, and `migration:revert` rolls back the last one. These scripts invoke the TypeORM CLI through a ts-node wrapper configured in the `typeorm` npm script.

## Authentication, Roles, and Social Login

The boilerplate ships with sign-in and sign-up via email, social sign-in through Apple, Facebook, and Google, and two roles: Admin and User. Session handling and JWT configuration are pre-wired through @nestjs/config. The authentication module is part of the src/ source tree and is designed to be extended.

The mailing layer uses nodemailer, configured through the environment file. The Maildev container in the Docker Compose setup catches outgoing mail locally without sending anything, which is the intended setup for development. Internationalisation is handled through nestjs-i18n: translation files are part of the repository and the i18n configuration is set up in the NestJS module.

File uploads support two storage drivers: local filesystem and Amazon S3. The driver is selected through an environment variable. Switching between them requires changing that variable, not rewriting upload logic.

## Running the Boilerplate with Docker and the Startup Scripts

The Dockerfile uses node:24.14.1-alpine as its base image and installs @nestjs/cli, typescript, and ts-node globally. It copies the package files, runs npm install, copies the application source, runs the build step, and starts the API via a startup script.

To start the relational setup locally:

```bash
cp env-example-relational .env
```

Then bring up the services with Docker Compose:

```bash
docker compose up
```

The startup.relational.dev.sh script is the entry point for the development container. The separate startup.relational.ci.sh and startup.relational.test.sh scripts handle CI and test environments respectively. The wait-for-it.sh script handles service dependency ordering, pausing the API container until Postgres is ready before attempting the connection.

E2E tests run against a dedicated test compose configuration (docker-compose.relational.test.yaml). Unit tests run independently of Docker.

## Code Generators: Seeding and Resource Scaffolding

The boilerplate uses hygen for code generation. Several npm scripts wrap the generator commands. To create a new resource with TypeORM support:

```bash
npm run generate:resource:relational
```

For Mongoose:

```bash
npm run generate:resource:document
```

For a resource that targets both database backends:

```bash
npm run generate:resource:all-db
```

Each generator creates the module, service, controller, DTO, and entity files in the correct structure. There are also property generators for adding a field to an existing entity across one or both backends. Seed creation follows a similar pattern: `seed:create:relational` and `seed:create:document` scaffold a new seeder file. All generator and seed commands run a lint fix step automatically via a post-hook in package.json.

## Limitations and When This Boilerplate Does Not Fit

The boilerplate is narrowly designed for REST APIs. There is no GraphQL module, no WebSocket gateway, and no gRPC setup in the repository. Teams who need those transport layers will need to add them from scratch.

The database support covers Postgres and MongoDB only. If your project uses MySQL, SQLite, or a different SQL dialect, TypeORM supports those but the boilerplate's migration scripts, Docker Compose files, and environment examples are configured for Postgres only. Adapting the Docker Compose and environment files is straightforward, but the relational mode is tested against Postgres specifically.

The file upload S3 driver requires AWS credentials in the environment. The README does not document a local MinIO substitute for development, so local S3-compatible testing requires additional configuration beyond what the boilerplate provides. The social login providers each require separate OAuth credentials from Apple, Facebook, and Google developer consoles before they work in any environment.

## Maintenance, License, and Alternatives

The last push to the repository was on 2026-09-25. The project is MIT licensed, permitting use in commercial and private projects without requiring derivative works to be open-source. The repository has no GitHub releases; version 1.2.0 appears in package.json, and a CHANGELOG.md documents changes.

The main alternative in the NestJS ecosystem is the official NestJS CLI-generated project (nest new), which provides a bare-bones structure without authentication, database setup, or file uploads. Teams who want a more prescriptive foundation choose boilerplates like this one. Another alternative is the NestJS official sample repository for TypeORM, which demonstrates ORM integration without the full authentication and mailing stack. The Brocoders boilerplate is more opinionated but provides more of the production plumbing out of the box.

## Conclusion

brocoders/nestjs-boilerplate is the right starting point for teams building a TypeScript NestJS REST API who want authentication, dual-database support, and code generators wired up before writing the first domain feature. It is not the right choice for teams who need GraphQL, WebSocket-first APIs, or a database outside Postgres and MongoDB. Before starting, copy env-example-relational or env-example-document to .env and review it: the file controls which database mode the application starts in, and missing environment variables will prevent the startup scripts from running. The CHANGELOG.md documents version history for tracking what changed between updates to your fork.

## FAQ

### How do I choose between the relational and document mode in brocoders/nestjs-boilerplate?

Copy env-example-relational to .env for a Postgres setup with TypeORM, or env-example-document for a MongoDB setup with Mongoose. Each mode has its own startup scripts and Docker Compose files. The two modes are separate configurations, not a runtime switch.

### How do I run database migrations in brocoders/nestjs-boilerplate?

Use the npm migration scripts: npm run migration:generate to create a new migration file, npm run migration:run to apply pending migrations, and npm run migration:revert to roll back the last one. These scripts work only in the relational (TypeORM) mode.

### Does brocoders/nestjs-boilerplate support social login out of the box?

Yes. The boilerplate includes sign-in via Apple, Facebook, and Google in addition to email-based sign-in. Each social provider requires OAuth credentials from the respective developer console, configured through environment variables.

## Sources

- [brocoders/nestjs-boilerplate on GitHub](https://github.com/brocoders/nestjs-boilerplate)
- [Issues](https://github.com/brocoders/nestjs-boilerplate/issues)
- [License: MIT](https://github.com/brocoders/nestjs-boilerplate/blob/main/LICENSE)
- [Project website](https://nestjs-boilerplate-test.herokuapp.com/docs)
- [README](https://github.com/brocoders/nestjs-boilerplate/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brocoders-nestjs-boilerplate