NestJS Development Rules
Overview
This skill provides procedural rules for working with NestJS in this project. It covers component generation, testing patterns, module structure, and deployment configuration. For GraphQL-specific patterns (resolvers, types, auth decorators), use the nestjs-graphql skill.
Component Generation
Always use NestJS CLI to create components rather than manually creating files.
Module Generation
bunx nest g module <name> --no-spec
Service Generation
bunx nest g service <name> --no-spec
Resolver Generation (GraphQL)
bunx nest g resolver <name> --no-spec
Controller Generation (REST)
bunx nest g controller <name> --no-spec
Why --no-spec
The --no-spec flag is used because this project follows TDD (Test-Driven Development). Tests are written first with a custom test structure before implementation, not auto-generated by the CLI.
Database Migrations
Entity Files Are the Source of Truth
In this project, entity files (src/database/entities/*.ts) are the single source of truth for the database schema. Migrations are a derived artifact — TypeORM diffs the entity metadata against the current database and emits the migration for you. For any change an entity can express, the workflow is:
- Edit the entity file to express the desired schema.
- Run
bun run migration:generate --name=<DescriptiveName>to produce the migration from the diff. - Review the generated migration, then commit both the entity change and the migration together.
Generate Schema Migrations
Use migration:generate from package.json for changes represented by entity metadata:
bun run migration:generate --name=<DescriptiveName>
Hand-Written Migrations
Some changes cannot be expressed in an entity, so they cannot come from an entity diff:
- Database objects TypeORM does not model (view options, grants, functions, row-level security policies)
- Seed data (reference rows, lookup tables, initial admin user)
- Data backfills (populating a new column from existing rows)
- Data transformations (splitting a column, normalizing values)
- One-off cleanup (deleting orphaned rows before a constraint is added)
- Database maintenance (refreshing planner statistics with
ANALYZE)
Writing these migrations directly is fine. The rule is: if the change can be expressed in an entity, edit the entity and run bun run migration:generate --name=<Name>; if it can't, write the migration. A hand-written migration documents why it was written by hand, and how it was verified, in its class comment so future readers understand why it was not generated. A generated migration needs no such note.
Enforcement
The lisa-nestjs plugin's default PreToolUse hook (block-migration-edits.sh) warns but does not refuse Write/Edit on paths matching **/migrations/*.ts or **/migrations/*.js. On Claude Code the warning reaches the agent as additionalContext and the edit continues through the normal permission flow. The hook keeps its historical name. The point of the warning is drift: a hand-written migration for a change an entity could express will drift from the entity definitions.
Per-agent delivery:
- Claude Code (and the Cursor, Copilot and Devin variants built from the same script): warning as PreToolUse JSON
additionalContext. Withoutjqthe hook cannot parse the payload, so it permits the edit with a note on stderr instead of the warning. - Codex: also inspects
apply_patchand matches numbered TypeScript migration filenames. Codex does not honoradditionalContexton PreToolUse, so the warning is written to stderr and is not known to reach the model. - OpenCode:
tool.execute.afterappends the warning to the edit/write tool output after the write.
A project that wants to enforce its own migration policy can declare a migration-provenance check at pre-tool in .lisa.config.json. The Claude and Codex hooks run that check for the targeted migration instead of warning, and refuse the edit when it fails. The check must validate the project's migration policy; an unconditional success command proves nothing. The declared check needs jq: without it the hooks cannot read the target path, so they permit the edit without running the check and say so on stderr. OpenCode's adapter does not run the declared check.
Why Auto-Generation
TypeORM compares your entity definitions against the current database schema to generate migrations. Manual creation can:
- Introduce drift between entities and migrations
- Miss important schema changes
- Create migrations that don't match entity metadata
Test-Driven Development Pattern
Write Tests First
Create test files before implementation:
// src/feature/feature.service.test.ts
import { Test, TestingModule } from "@nestjs/testing";
import { FeatureService } from "./feature.service";
describe("FeatureService", () => {
const service: FeatureService;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [FeatureService],
}).compile();
service = module.get<FeatureService>(FeatureService);
});
describe("methodName", () => {
it("should do expected behavior", () => {
expect(service.methodName()).toBe("expected");
});
});
});
Test File Naming
- Unit tests:
*.test.ts - Integration tests:
*.integration.test.ts
Running Tests
# Unit tests only
bun run test:unit
# Integration tests only
bun run test:integration
# All tests
bun run test
Module Structure
Feature Module Pattern
src/
├── <feature>/
│ ├── <feature>.module.ts # Module definition
│ ├── <feature>.service.ts # Business logic
│ ├── <feature>.service.test.ts # Service unit tests
│ ├── <feature>.resolver.ts # GraphQL resolver (if applicable)
│ ├── <feature>.resolver.test.ts # Resolver unit tests
│ ├── <feature>.controller.ts # REST controller (if applicable)
│ ├── <feature>.controller.test.ts
│ ├── dto/ # Data transfer objects
│ │ ├── create-<feature>.input.ts
│ │ └── update-<feature>.input.ts
│ └── entities/ # Entity definitions
│ └── <feature>.entity.ts
Module Registration
Register feature modules in app.module.ts:
import { Module } from "@nestjs/common";
import { FeatureModule } from "./feature/feature.module";
@Module({
imports: [
// ... other imports
FeatureModule,
],
})
export class AppModule {}
Lambda Handler Pattern
Entry Point Structure
// src/main.ts
import { NestFactory } from "@nestjs/core";
import { configure as serverlessExpress } from "@vendia/serverless-express";
import { AppModule } from "./app.module";
type ServerlessHandler = ReturnType<typeof serverlessExpress>;
/**
* Creates a lazy-initialized server getter using closure pattern
* @description Encapsulates mutable cache state for Lambda warm starts
* @returns Async function that returns the cached or newly created server
*/
const createServerGetter = (): (() => Promise<ServerlessHandler>) => {
// eslint-disable-next-line functional/no-let -- Required for Lambda warm start caching
let cachedServer: ServerlessHandler | null = null;
return async (): Promise<ServerlessHandler> => {
if (cachedServer) {
return cachedServer;
}
const nestApp = await NestFactory.create(AppModule, {
cors: {
origin: "*",
methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
preflightContinue: false,
optionsSuccessStatus: 204,
},
});
await nestApp.init();
const app = nestApp.getHttpAdapter().getInstance();
cachedServer = serverlessExpress({ app });
return cachedServer;
};
};
const getServer = createServerGetter();
/**
* Lambda handler function
* @param event - AWS Lambda event object
* @param context - AWS Lambda context object
* @returns Promise resolving to Lambda response
*/
export const handler = async (
event: unknown,
context: unknown
): Promise<unknown> => {
const server = await getServer();
return server(event, context);
};
Key Lambda Concepts
- Warm Start Caching: Use closure pattern to cache the NestJS application between invocations
- Serverless Express: Use
@vendia/serverless-expressfor Express adapter compatibility - CORS Configuration: Configure CORS in NestFactory.create(), not in serverless.yml
Configuration Files
NestJS CLI Configuration
// nest-cli.json
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true
}
}
TypeScript Configuration
Required settings for NestJS decorators:
// tsconfig.json (additions)
{
"compilerOptions": {
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"strictPropertyInitialization": false
}
}
Serverless Framework Configuration
# serverless.yml
service: project-name
frameworkVersion: "^4.0.0"
custom:
esbuild:
bundle: true
minify: false
sourcemap: true
keepNames: true
platform: node
target: node20
external:
- "fsevents"
- "@nestjs/websockets"
- "@nestjs/microservices"
- "@apollo/gateway"
- "@apollo/subgraph"
- "@as-integrations/fastify"
- "class-transformer/storage"
plugins:
- serverless-esbuild
- serverless-offline
provider:
name: aws
runtime: nodejs22.x
region: us-east-1
httpApi:
cors: true
functions:
main:
handler: src/main.handler
timeout: 29
memorySize: 1024
events:
- httpApi:
method: any
path: /{proxy+}
Documentation Standards
JSDoc for All Components
Every exported function, class, and type must have JSDoc documentation:
/**
* Service for managing user accounts
* @description Provides CRUD operations for user entities
* @remarks
* - All methods are idempotent
* - Throws NotFoundException for missing resources
*/
@Injectable()
export class UserService {
/**
* Retrieves a user by their unique identifier
* @param id - The unique identifier of the user
* @returns The user if found, null otherwise
*/
async findById(id: string): Promise<User | null> {
return this.repository.findOne({ where: { id } });
}
}
Module File Preambles
Every file should have a preamble comment:
/**
* @file user.service.ts
* @description Service providing user account management
* @module users
*/
DataLoader Integration
Batch Method Pattern
Services that support DataLoader must implement batch methods:
/**
* Batch loads entities by IDs (for DataLoader)
* @param ids - Array of entity IDs to load
* @returns Promise resolving to array of entities in same order as input
* @remarks Used by DataLoader for batching - maintains input order
*/
async findByIds(ids: readonly string[]): Promise<Entity[]> {
const entities = await this.repository.findBy({ id: In([...ids]) });
const entityMap = new Map(entities.map(e => [e.id, e]));
return ids.map(id => entityMap.get(id) ?? null);
}
Order Preservation
Batch functions must return results in the same order as input keys. Always map input IDs to results to maintain order.
Common Patterns
Immutable Code
Use const instead of let or var:
// Good
const users = await this.userService.findAll();
const filtered = users.filter(u => u.active);
// Bad
let users = await this.userService.findAll();
users = users.filter(u => u.active);
Functional Transformations
Use reduce instead of push or pop:
// Good
const userMap = users.reduce(
(acc, user) => ({ ...acc, [user.id]: user }),
{} as Record<string, User>
);
// Bad
const userMap: Record<string, User> = {};
users.forEach(user => {
userMap[user.id] = user;
});
Error Handling
Use GraphQL errors with codes:
import { GraphQLError } from "graphql";
throw new GraphQLError("User not found", {
extensions: { code: "NOT_FOUND", id },
});
Configuration Management
Never Use process.env Directly
Always use NestJS ConfigService instead of accessing process.env directly. This provides:
- Type safety with full autocomplete
- Centralized configuration management
- Easier testing (mock ConfigService instead of environment)
- Validation at startup
ConfigService in NestJS Context
For services, resolvers, and controllers running within NestJS:
import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { Configuration } from "../config/configuration";
@Injectable()
export class MyService {
constructor(
private readonly configService: ConfigService<Configuration, true>
) {}
someMethod(): void {
// Type-safe configuration access with autocomplete
const host = this.configService.get("database.host", { infer: true });
const isOffline = this.configService.get("app.isOffline", { infer: true });
}
}
ConfigService in Module Factories
For dynamic module configuration (e.g., TypeOrmModule.forRootAsync):
import { Module } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { TypeOrmModule } from "@nestjs/typeorm";
import { Configuration } from "../config/configuration";
@Module({
imports: [
TypeOrmModule.forRootAsync({
inject: [ConfigService],
useFactory: (configService: ConfigService<Configuration, true>) =>
createTypeOrmOptionsFromConfigService(configService),
}),
],
})
export class DatabaseModule {}
Standalone Configuration (Lambda Handlers)
For code running outside NestJS context (Lambda authorizers, WebSocket handlers):
import { getStandaloneConfig } from "../../config/configuration";
// Use getStandaloneConfig() for type-safe access outside NestJS
const config = getStandaloneConfig();
const host = config.valkey.host;
const port = config.valkey.port;
Configuration Schema
All configuration is defined in src/config/configuration.ts:
export interface Configuration {
readonly app: {
readonly nodeEnv: string;
readonly isOffline: boolean;
};
readonly database: {
readonly host: string;
readonly port: number;
readonly username: string;
readonly password: string;
readonly name: string;
// ... other database config
};
readonly valkey: {
readonly host: string;
readonly port: number;
readonly maxRetriesPerRequest: number;
};
// ... other configuration namespaces
}
Adding New Configuration
- Add the new property to the
Configurationinterface - Add default values in the
configuration()factory function - Access via
configService.get("namespace.property", { infer: true })
Testing with ConfigService
Create mock ConfigService in tests:
const createMockConfigService = (): ConfigService<Configuration, true> => {
const config = {
valkey: { host: "localhost", port: 6379, maxRetriesPerRequest: 3 },
};
return {
get: jest.fn((key: string) => {
const keys = key.split(".");
return keys.reduce((obj, k) => obj?.[k], config);
}),
} as unknown as ConfigService<Configuration, true>;
};
// In test setup
const module = await Test.createTestingModule({
providers: [
MyService,
{ provide: ConfigService, useValue: createMockConfigService() },
],
}).compile();
Verification Checklist
After creating or modifying NestJS components:
- Unit tests pass:
bun run test:unit - Integration tests pass:
bun run test:integration - Linting passes:
bun run lint - Type check passes:
bun run build - Local server starts:
bun run start:local