Skip to main content
rule CX Codex

lambda-conventions — Claude Code rule: AWS Lambda structure with NestJS

lambda-conventions establishes directory structure, file naming, and validation patterns for AWS Lambda functions built with NestJS and deployed via SAM. Keeps handler implementations and configs consistent across a team.

MIT ★ 372 updated 2026-09-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kit
Open on GitHub

What lambda-conventions does

The rule defines a project layout at apps/lambdas/{domain}/{lambda-name}/, project naming like lambda-admin-create-tenant, and handler classes like CreateTenantHandler. Handlers follow a six-step pipeline: HTTP method check, body size validation, JSON parsing, Zod schema validation, business logic, and error handling.

Each Lambda requires bootstrap.ts as entry point, a modules folder with validate-env.ts for environment schema, app.module.ts for NestJS setup, a SAM template at template.yaml, and samconfig.toml for deployment. Handlers must use the shared bootstrapLambda function from @sibill-erp-gateway/server/lambda-core.

The project.json must include targets: bundle (esbuild to CommonJS), test (Jest), lint (ESLint), sam-build, sam-deploy, sam-local for Docker-based local invocation, and serve for local API. Requires Node.js 22.x and integrates with DynamoDB, API Gateway, and other AWS services configured in the SAM template.

What it helps with

  • set up a consistent project structure for AWS Lambda with NestJS
  • standardize request handlers and their test patterns
  • validate environment variables at Lambda startup
  • deploy functions through SAM with proper build targets
  • run and debug Lambda locally using Docker

Example prompts for the agent

  • Create a Lambda function using apps/lambdas/admin/create-tenant/project.json as a template
  • Add environment validation in validate-env.ts with a Zod schema
  • Implement the handler following the six-step pipeline in src/handlers/create-tenant.handler.ts

How to install lambda-conventions

1Plugin marketplace

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kit

2Manually: put the files in place

.claude/rules/lambda-conventions.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about lambda-conventions

How do I install lambda-conventions in Claude Code?

Run /plugin marketplace add giuseppe-trisciuoglio/developer-kit, then /plugin install developer-kit-typescript@developer-kit. The rule will be available at .claude/rules/lambda-conventions.md.

What does the lambda-conventions rule do?

It defines directory structure, file naming conventions, and handler patterns for AWS Lambda on NestJS, enforces a six-step request validation pipeline, requires Zod schemas for environment validation, and specifies SAM configuration for deployment.

What dependencies do I need for lambda-conventions?

Node.js 22.x, NestJS, Zod for schema validation, SAM CLI for deployment, and the @sibill-erp-gateway/server/lambda-core package for shared handler utilities. Docker is required for local testing via sam-local.

Source text

lambda-conventions.md · MIT
---
paths:
  - "**/*.ts"
---
# Rule: Lambda Conventions

## Context
Enforce consistent patterns for AWS Lambda functions built with NestJS and deployed via SAM. Lambda handlers follow a 6-step validation pipeline and integrate with shared server features.

## Guidelines

### Lambda Directory Structure

```
apps/lambdas/{domain}/{lambda-name}/
├── src/
│   ├── bootstrap.ts              # Entry point - exports handler
│   ├── handlers/
│   │   ├── index.ts              # Barrel export
│   │   └── {action}-{entity}.handler.ts    # HTTP request handler
│   │   └── {action}-{entity}.handler.spec.ts # Unit tests
│   │   └── {action}-{entity}.handler.integration.spec.ts # Integration tests
│   └── modules/
│       ├── index.ts              # Barrel export
│       ├── app.module.ts         # Root NestJS module
│       └── validate-env.ts       # Environment validation schema
├── template.yaml                 # SAM template
├── samconfig.toml                # SAM deployment config
├── project.json                  # Nx project configuration
├── jest.config.ts                # Jest configuration
├── tsconfig.json                 # TypeScript config
├── events/                       # Test events for local invoke
│   └── {action}-{entity}.json
├── env.json                      # Local environment variables
└── scripts/
    └── local-dev.sh              # Local development script
```

### Naming Conventions

| Element | Pattern | Example |
|---|---|---|
| Project name | `lambda-{domain}-{action}-{entity}` | `lambda-admin-create-tenant` |
| Handler class | `{Action}{Entity}Handler` | `CreateTenantHandler` |
| Handler file | `{action}-{entity}.handler.ts` | `create-tenant.handler.ts` |
| Module file | `app.module.ts` | `app.module.ts` |
| Env validator | `validate-env.ts` | `validate-env.ts` |

### Project Configuration (project.json)

Use `apps/lambdas/admin/create-tenant/project.json` as template:

- **`name`**: `lambda-{domain}-{action}-{entity}`
- **`sourceRoot`**: `apps/lambdas/{domain}/{lambda-name}/src`
- **`tags`**: `["scope:lambda", "type:{domain}"]`
- **`targets`**:
  - `bundle`: esbuild CJS output
  - `test`: Jest unit tests
  - `lint`: ESLint
  - `sam-build`: SAM build
  - `sam-deploy`: SAM deploy
  - `sam-local`: Local invoke with Docker
  - `serve`: SAM local API

### Bootstrap Pattern

```typescript
// src/bootstrap.ts
import 'reflect-metadata';
import { bootstrapLambda } from '@sibill-erp-gateway/server/lambda-core';
import { AppModule } from './modules';
import { CreateTenantHandler } from './handlers';

export const handler = bootstrapLambda(AppModule, CreateTenantHandler);
```

### Handler Pattern (6-Step Validation Pipeline)

```typescript
// src/handlers/create-tenant.handler.ts
@Injectable()
export class CreateTenantHandler extends BaseLambdaHandlerService {
  constructor(
    @Inject(MY_SERVICE)
    private readonly myService: MyService,
  ) {
    super();
  }

  async handle(event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> {
    const requestId = context.awsRequestId;
    const startTime = Date.now();

    // 1. Validate HTTP method
    const methodError = this.validateHttpMethod(event, ['POST']);
    if (methodError) return methodError;

    // 2. Validate body size
    const sizeValidation = validateBodySize(event.body);
    if (!sizeValidation.valid) {
      this.logger.warn({ requestId }, 'Request body too large');
      return sizeValidation.response;
    }

    // 3. Parse JSON safely
    const parseResult = safeJsonParse(event.body);
    if (!parseResult.success) {
      this.logger.warn({ requestId }, 'Invalid JSON payload');
      return parseResult.response;
    }

    // 4. Validate with Zod schema
    const validationResult = MySchema.safeParse(parseResult.data);
    if (!validationResult.success) {
      this.logger.warn({ requestId }, 'Input validation failed');
      return validationErrorResponse(validationResult.error.issues);
    }

    // 5. Execute business logic
    try {
      const result = await this.myService.execute(validationResult.data, requestId);
      return successResponse(HttpStatus.CREATED, result);
    } catch (error: unknown) {
      return handleLambdaError(error, requestId, this.logger);
    }
  }
}
```

### Environment Validation

```typescript
// src/modules/validate-env.ts
import { z } from 'zod';

const environmentSchema = z.object({
  MY_TABLE: z.string().min(1, 'MY_TABLE is required'),
  COUNTERS_TABLE: z.string().min(1, 'COUNTERS_TABLE is required'),
  DYNAMODB_ENDPOINT: z.string().optional(),
  AWS_REGION: z.string().optional(),
  NODE_ENV: z.string().optional(),
});

export type EnvironmentVariables = z.infer<typeof environmentSchema>;

export function validate(config: Record<string, unknown>): EnvironmentVariables {
  const parsed = environmentSchema.safeParse(config);
  if (!parsed.success) {
    const errors = parsed.error.issues.map(i => `[${i.path.join('.')}]: ${i.message}`).join('\n');
    throw new Error(`Environment validation failed:\n${errors}`);
  }
  return parsed.data;
}
```

### App Module Configuration

```typescript
// src/modules/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { MyHandler } from '../handlers';
import { MyFeatureModule } from '@sibill-erp-gateway/server/my-feature';
import { type EnvironmentVariables, validate } from './validate-env';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validate,
    }),
    MyFeatureModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        tableName: config.get<string>('MY_TABLE')!,
        countersTableName: config.get<string>('COUNTERS_TABLE')!,
        endpoint: config.get<string>('DYNAMODB_ENDPOINT'),
        region: config.get<string>('AWS_REGION') || 'eu-central-1',
      }),
      inject: [ConfigService],
    }),
  ],
  providers: [MyHandler],
})
export class AppModule {}
```

### SAM Template Structure

```yaml
# template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 30
    MemorySize: 512
    Runtime: nodejs22.x
    Environment:
      Variables:
        AWS_REGION: !Ref AWS::Region

Parameters:
  Environment:
    Type: String
    Default: dev
    AllowedValues: [dev, staging, prod]

Resources:
  # DynamoDB Tables
  MyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: !Sub 'sg-my-table-${Environment}'
      # ... table configuration

  # API Gateway
  ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !Ref Environment
      # ... API configuration

  # Lambda Function
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: !Sub '${Environment}-my-action-entity'
      Handler: main.handler
      CodeUri: ../../../../dist/apps/lambdas/{domain}/{lambda-name}
      Events:
        MyApi:
          Type: Api
          Properties:
            RestApiId: !Ref ApiGateway
            Path: /{domain}/{entity}
            Method: POST
      Environment:
        Variables:
          MY_TABLE: !Ref MyTable
          DYNAMODB_ENDPOINT: ''
          NODE_ENV: 'production'
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref MyTable

Outputs:
  ApiGatewayEndpoint:
    Value: !Sub 'https://${ApiGateway}.execute-api.${AWS::Region}.amazonaws.com/${Environment}'
```

### DTO Pattern

**Write DTOs (Zod schemas)** in `libs/shared/{entity}-dto/`:

```typescript
// libs/shared/tenant-dto/src/lib/create-tenant.schema.ts
import { z } from 'zod';

export const CreateTenantSchema = z.object({
  tenantName: z.string().trim().min(1, 'Tenant name is required').max(255),
  vatNumber: z.string().trim().min(1).regex(/^IT\d{11}$/u, 'Invalid VAT format'),
  adminEmail: z.string().trim().toLowerCase().pipe(z.email()),
});

export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
```

**Read DTOs (Interfaces)** in `libs/shared/{entity}-dto/`:

```typescript
// libs/shared/tenant-dto/src/lib/tenant.dto.ts
export interface TenantDto {
  readonly tenantId: string;
  readonly tenantName: string;
  readonly vatNumber: string;
  readonly adminEmail: string;
  readonly status: TenantStatus;
  readonly createdAt?: string;
}
```

**Enums** in `libs/shared/{entity}-dto/`:

```typescript
// libs/shared/tenant-dto/src/lib/tenant-status.enum.ts
export enum TenantStatus {
  Created = 'created',
  Active = 'active',
  Suspended = 'suspended',
  Deleted = 'deleted',
}
```

## Examples

### ✅ Good

```typescript
// Handler with full 6-step pipeline
export class CreateTenantHandler extends BaseLambdaHandlerService {
  async handle(event: APIGatewayProxyEvent, context: Context) {
    // 1-6: All steps implemented
    const methodError = this.validateHttpMethod(event, ['POST']);
    if (methodError) return methodError;
    // ... rest of pipeline
  }
}
```

### ❌ Bad

```typescript
// Missing validation steps
async handle(event, context) {
  const body = JSON.parse(event.body || '{}'); // No safe parse, no size check
  const result = await this.service.create(body); // Direct call without validation
  return result;
}
```

## Commands

### Development

```bash
# Bundle Lambda
nx bundle lambda-admin-create-tenant

# Run tests
nx test lambda-admin-create-tenant
nx test lambda-admin-create-tenant --testPathPattern=handler.spec.ts

# SAM local (requires DynamoDB Local running)
nx serve lambda-admin-create-tenant
nx sam-local lambda-admin-create-tenant

# Deploy
nx deploy lambda-admin-create-tenant
nx deploy lambda-admin-create-tenant --configuration=staging
nx deploy lambda-admin-create-tenant --configuration=prod
```

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Similar IDE rules

All IDE rules for Backend and APIs →

From the same set191

The whole set →
nestjs-code-review-expert nestjs-code-review-expert is a Claude Code subagent that reviews NestJS changes and new features. It checks TypeScript practices, architecture, security, and tests. CX Codex ★ 372repo stars spring-boot-code-review-expert spring-boot-code-review-expert reads a Spring Boot diff and checks it against Java and Spring conventions. Returns findings ranked by severity, each with a code sample. CX Codex ★ 372repo stars general-code-explorer general-code-explorer traces feature implementations across codebases, maps call flows from entry points to data layers, and documents architectural patterns. CX Codex ★ 372repo stars devkit.generate-security-assessment The devkit.generate-security-assessment command turns project structure and audit findings into a structured security assessment. Use it after an audit when you need a report in a chosen language and format. CX Codex +1 ★ 372repo stars aws-cloudformation-ec2 aws-cloudformation-ec2 generates production-grade AWS CloudFormation templates for EC2 virtual servers, security groups, IAM instance profiles, and load balancers. CX Codex +1 ★ 372repo stars devkit.java.refactor-class devkit.java.refactor-class — a Claude Code command that inspects a Java class and rewrites it following Clean Architecture, DDD, and Spring Boot patterns. Takes a file path, a refactoring scope, and optional flags like dry-run or backup. CX Codex +1 ★ 372repo stars general-debugger general-debugger takes a crash or a failing test down to the line that caused it: reads the stack trace, walks the execution path backwards, then suggests a small fix. CX Codex ★ 372repo stars document-generator-expert document-generator-expert generates technical assessments, feature specs, process docs, and analysis reports directly from your codebase. CX Codex ★ 372repo stars

Project sponsors

Companies that keep this analytics open