node-microservice-builder

Skill: Node Microservice Builder

Purpose

Create or modify Node.js/TypeScript microservice endpoints following backend conventions and best practices.

Inputs

• serviceName: Name of the service or module.
• endpointSpec: HTTP method, path, request/response schemas, and business logic description.
• targetFolder: Service directory within the project.

Outputs

• Controller or route handler file.
• Validation schemas (Zod, Joi, or class-validator).
• Test file with unit and integration tests.
• Updated routing configuration if needed.

Procedure

Step 1: Validate Inputs

1. Ensure serviceName follows the project's naming convention.
2. Verify targetFolder is a valid Node.js project (contains package.json).
3. Check for tsconfig.json to confirm TypeScript usage.

Step 2: Load Skill

Read: .agents/skills/node-typescript-service/SKILL.md

Follow the procedures defined in that skill.

Step 3: Detect Framework

Check package.json dependencies:

• express → Express.js
• @nestjs/core → Nest.js
• fastify → Fastify

Adjust code patterns accordingly.

Step 4: Generate Endpoint Handler

1. Create handler function with typed parameters.
2. Implement request validation using the project's validation library.
3. Add error handling with appropriate HTTP status codes.
4. Structure response with consistent format.

For Nest.js:

• Use controller class with decorators (@Controller, @Post, etc.).
• Inject dependencies via constructor.
• Use DTOs with validation decorators.

For Express:

• Create route handler function.
• Use middleware for validation.
• Return responses via res.status().json().

Step 5: Add Validation Schema

Refer to: .agents/skills/node-typescript-service/references/validation-and-errors.md

1. Define input schema (request body, query params, path params).
2. Use appropriate validation library based on framework:
   • NestJS: class-validator with DTOs:

     export class CreateUserDto {
       @IsString()
       @IsNotEmpty()
       @MaxLength(100)
       name!: string
     
       @IsEmail()
       email!: string
     
       @IsEnum(UserRole)
       role!: UserRole
     }
     

   • Express: Joi or Zod middleware
3. Ensure DTOs/schemas have explicit types (no any).
4. Use discriminated unions for variant request types.
5. Attach validation middleware or decorator.
6. Provide typed response DTOs separate from entities:

   export class UserResponseDto {
     id: string
     name: string
     email: string
     role: UserRole
   }