create-nestjs-api

Generic npm initializer for standalone NestJS APIs. It renders a maintained template into a new project and leaves the generated app with its own copied infrastructure code.

Usage

npx @juaoantonio/create-nestjs-api@latest
npx @juaoantonio/create-nestjs-api@latest my-api
pnpm dlx @juaoantonio/create-nestjs-api@latest my-api

Alias:

npx --package @juaoantonio/create-nestjs-api@latest create-nest-api my-api
pnpm dlx --package @juaoantonio/create-nestjs-api@latest create-nest-api my-api

Prompts

• Project directory: defaults to the CLI argument or nestjs-api.
• Package name: defaults from the project directory.
• Description: defaults to A NestJS API service.
• API prefix: defaults to v1.
• HTTP port: defaults to 3000.
• Package manager: pnpm, npm, or yarn; pnpm is recommended.
• Install dependencies: enabled by default.
• Initialize git: enabled by default.

Generated App

The generated app includes:

• NestJS 11 and TypeScript.
• ConfigModule with Joi validation and layered envs/.env* loading.
• TypeORM/PostgreSQL only.
• /v1/health by default, plus Swagger and Scalar docs under the configured API prefix.
• Winston console logging.
• Request IDs, global validation, success envelopes, exception envelopes, generic errors, and PostgreSQL error mapping.
• Spring-style PageDto<T> pagination helpers.
• Vitest, Supertest, Testcontainers helpers, Docker Compose PostgreSQL, and TypeORM migration scripts.

V1 intentionally excludes auth, users, Redis, queues, storage, email, CSRF, Loki/Grafana, MinIO, MailCatcher, and domain modules.

Local Development

pnpm install
pnpm build
pnpm test

Generate a local app without installing dependencies:

pnpm start

Verification Before Publish

Run the default local checks:

pnpm build
pnpm test
pnpm verify:template

pnpm verify:template renders templates/app into a temporary app, replaces starter placeholders, and inspects key generated files without Docker, dependency installation, package registry access, or other network calls.

Template Maintenance

Template files live in templates/app. The renderer replaces placeholders such as __PROJECT_NAME__, __PACKAGE_NAME__, __API_PREFIX__, __PORT__, and database values.

Before publishing package changes, run:

pnpm build
pnpm test
pnpm verify:template
npm pack --dry-run
npm publish --dry-run

Publish the public scoped package:

npm publish --access public

For a fuller generated-app check, generate a temporary app from the packed tarball, install dependencies, then run the generated app checks. These checks can require Docker and network access:

pnpm build
pnpm test
pnpm test:e2e
pnpm services:up
pnpm migration:run