nestjs-rules

NestJS Backend Services Rules

Project Structure

• This is a monorepo using pnpm and Turborepo
• NestJS apps are compiled with CommonJS (required for NestJS)
• Apps: auth, order, product
• All apps use NestJS 11.x with TypeScript 5.9.x

Critical: TypeScript Imports for Dependency Injection

❌ NEVER use type imports for services

// ❌ WRONG - Type imports are erased at compile time
import type { ConfigService } from '@nestjs/config';
import type { ClientService } from '@projectx/workflows';
import { type AuthService } from '@projectx/core';
// ✅ CORRECT - Regular imports for dependency injection
import { ConfigService } from '@nestjs/config';
import { ClientService } from '@projectx/workflows';
import { AuthService } from '@projectx/core';

When to use type imports:

• ✅ For interfaces and type aliases only
• ✅ For DTOs used only in type positions
• ✅ For types that are never instantiated

When NOT to use type imports:

• ❌ For classes decorated with @Injectable()
• ❌ For services used in constructor injection
• ❌ For any class that needs to exist at runtime
• ❌ For guards, interceptors, pipes, or filters

Module Configuration

Always export services that are used in other modules

@Module({
  providers: [MyService],
  exports: [MyService],  // ✅ Export if used elsewhere
})

ConfigModule should be global

ConfigModule.forRoot({
  isGlobal: true,  // ✅ Makes ConfigService available everywhere
  load: [appConfig, swaggerConfig, temporalConfig],
  validate: (config) => validateConfiguration(config, EnvironmentVariables),
})

Temporal Integration

All services use Temporal workflows

• Task queue configured via environment variable: temporal.taskQueue
• Workflow client accessed via ClientService from @projectx/workflows
• Always check if workflow client is initialized before use

Workflow client pattern:

getWorkflowClient() {
  const workflowClient = this.clientService.client?.workflow;
  if (!workflowClient) {
    throw new HttpException(
      'The workflow client was not initialized correctly',
      HttpStatus.INTERNAL_SERVER_ERROR,
    );
  }
  return workflowClient;
}