Copilot Instructions for golevelup/nestjs

Repository Overview

This is a pnpm monorepo containing a collection of NestJS modules and utilities. Each package lives under packages/ and is published independently to npm under the @golevelup scope.

Packages

Tech Stack

• Language: TypeScript 5.x (strict mode enabled)
• Framework: NestJS v11
• Package manager: pnpm v10 (workspaces)
• Monorepo tooling: Lerna v9 (independent versioning)
• Unit tests: Vitest v4 (Jest is only used inside the @golevelup/ts-jest and @golevelup/ts-sinon packages)
• Integration tests: Vitest v4
• Linter: Oxlint
• Formatter: Oxfmt
• Versioning/changelog: Changesets
• Commit conventions: Conventional Commits via Commitizen + CommitLint

Setup

pnpm i

Running pnpm i also registers Git hooks via Husky.

Build

# Build all packages (excludes rabbitmq-integration and google-cloud-pubsub-integration)
pnpm build

# Build in watch mode
pnpm build:watch

# Clean build artifacts
pnpm clean

Testing

# Run all unit tests
pnpm test

# Run unit tests in CI mode (with coverage)
pnpm test:ci

# Run integration tests (requires running RabbitMQ - see docker-compose.yml)
pnpm test:integration

# Run integration tests in CI mode
pnpm test:ci:integration

# Run Vitest unit tests
pnpm test:vitest

# Run Vitest in CI mode with coverage
pnpm test:vitest:ci

Integration tests require external services. Use docker-compose.yml to start them locally:

docker compose up -d

Environment variables for integration tests:

• RABBITMQ_HOST – RabbitMQ hostname (default: localhost)
• RABBITMQ_PORT – RabbitMQ port (default: 5672)

Linting & Formatting

# Lint
pnpm lint

# Format all files
pnpm format

# Check formatting without modifying files
pnpm format:check

Type Checking

pnpm lerna:typecheck

Coding Conventions

• All code is TypeScript with strict: true. Do not disable strict checks.
• Follow existing NestJS module patterns: modules export a DynamicModule via a static forRoot() or forRootAsync() method.
• Use decorators and metadata reflection (reflect-metadata) for NestJS integration points.
• Prefer async/await over raw Promises or callbacks.
• All new features must include corresponding unit tests.
• Tests live alongside source files (e.g., src/foo.spec.ts) or in a dedicated __tests__ directory within the package.
• Do not add new dependencies without checking for existing alternatives already present in the workspace.
• Each package has its own package.json. Add package-level dependencies to the correct package, not the root.

Commit Conventions

Commits must follow the Conventional Commits specification. Use the interactive prompt to generate compliant messages:

pnpm commit

Reference issue numbers in the commit footer using closes #<number> or refs #<number>.

Branch naming:

• feature/{number}-short-description
• fix/{number}-short-description
• docs/short-description

Versioning & Publishing

Versions are managed independently per package using Changesets. To create a changeset for your changes:

pnpm prep-release

Do not manually edit package.json version fields or CHANGELOG.md files; let the Changesets tooling handle those.

CI

The CI pipeline (.github/workflows/ci.yml) runs on every pull request and executes:

1. Install dependencies (pnpm i --prefer-offline)
2. Build all packages (pnpm build)
3. Lint (pnpm lint)
4. Type check (pnpm lerna:typecheck)
5. Unit tests (pnpm test:ci)
6. Vitest tests (pnpm test:vitest:ci)
7. Integration tests (pnpm test:ci:integration)

All steps must pass before a PR can be merged.

What Not to Do

• Do not modify pnpm-lock.yaml directly; let pnpm i manage it.
• Do not commit build artifacts (lib/, *.tsbuildinfo) — they are gitignored.
• Do not skip or delete existing tests to make a build pass.
• Do not introduce breaking changes to public APIs without a corresponding changeset and major version bump.
• Do not use Jest for unit or integration tests; use Vitest instead. The only exception is the @golevelup/ts-jest package itself.