---
name: nodejs-api-scaffold
category: nodejs
priority: medium
tags:
  - nodejs
  - express
  - api
  - typescript
  - scaffold
mcpTools:
  - context7
---

# Node.js API Scaffolding Command

Generate production-ready Node.js REST API with Context7-verified best practices.

## Required Documentation Access

**MANDATORY:** Before scaffolding, query Context7 for best practices:

**Documentation Queries:**
- `mcp://context7/nodejs/node` - Event loop, async iterators (for await...of), Symbol.asyncIterator, AbortSignal
- `mcp://context7/airbnb/javascript` - ES6 patterns, object shorthand, spread syntax
- `mcp://context7/agile/api-design` - REST API design patterns
- `mcp://context7/project-management/project-structure` - Node.js project organization

**Why This is Required:**
- Ensures use of latest Node.js async iteration patterns
- Applies ES6 best practices from Airbnb style guide
- Implements AbortSignal for request cancellation
- Uses Symbol.asyncIterator for custom iterators
- Follows modern JavaScript syntax patterns
- Optimizes event loop performance

## Purpose

Create a complete Node.js/Express API with TypeScript following Context7 best practices:
- Async/await with proper error handling
- ES6 syntax (object shorthand, spread, destructuring)
- Symbol.asyncIterator for streams
- AbortSignal for cancellation
- Middleware architecture
- Database integration (Prisma/TypeORM)
- JWT authentication
- Testing with Jest
- Docker containerization

## Usage

```bash
/nodejs:api-scaffold <project-name> [options]
```

## Options

- `--framework <type>` - Framework (express, fastify, nestjs) [default: express]
- `--db <type>` - Database (postgresql, mongodb, mysql) [default: postgresql]
- `--orm <type>` - ORM (prisma, typeorm, sequelize) [default: prisma]
- `--auth` - Include JWT authentication [default: true]
- `--docker` - Include Dockerfile and docker-compose [default: true]
- `--tests` - Include Jest setup [default: true]

## Generated Structure

```
<project-name>/
├── src/
│   ├── index.ts             # Entry point with ES6 exports
│   ├── app.ts               # Express app configuration
│   ├── server.ts            # Server startup
│   ├── config/
│   │   └── index.ts         # Environment configuration
│   ├── controllers/
│   │   └── user.controller.ts  # Request handlers
│   ├── services/
│   │   └── user.service.ts     # Business logic
│   ├── models/
│   │   └── user.model.ts       # Data models
│   ├── middlewares/
│   │   ├── auth.middleware.ts  # JWT verification
│   │   ├── error.middleware.ts # Error handling
│   │   └── logger.middleware.ts # Logging
│   ├── routes/
│   │   └── user.routes.ts      # API routes
│   ├── utils/
│   │   ├── asyncHandler.ts     # Async wrapper
│   │   └── AppError.ts         # Custom error class
│   └── types/
│       └── index.ts            # TypeScript types
├── prisma/
│   └── schema.prisma        # Database schema
├── tests/
│   ├── setup.ts             # Test configuration
│   └── user.test.ts         # API tests
├── package.json             # npm configuration
├── tsconfig.json            # TypeScript config
├── Dockerfile               # Multi-stage build
├── docker-compose.yml       # Development setup
└── README.md
```

## Implementation Steps

1. **Query Context7 Documentation** (MANDATORY FIRST STEP)
   - Retrieve Node.js async iteration patterns (for await...of)
   - Get ES6 syntax best practices (Airbnb guide)
   - Access AbortSignal usage for cancellation
   - Review Symbol.asyncIterator implementation

2. **Create Project Structure**
   - Initialize npm/yarn project with TypeScript
   - Setup tsconfig.json
   - Install dependencies

3. **ES6 Configuration** (Using Context7 Airbnb patterns)
   ```typescript
   // src/config/index.ts
   // ES6 default parameters
   export const config = {
     port: process.env.PORT ?? 3000,
     database: {
       host: process.env.DB_HOST,
       port: process.env.DB_PORT ?? 5432,
       ...getAdditionalConfig(), // ES6 spread
     },
   };

   // Object method shorthand
   export const logger = {
     info(message: string) {
       console.log(`[INFO] ${message}`);
     },
     error(message: string) {
       console.error(`[ERROR] ${message}`);
     },
   };
   ```

4. **Async Iteration Setup** (Context7 Node.js patterns)
   ```typescript
   // src/utils/streamProcessor.ts
   import { once } from 'node:events';
   import * as readline from 'node:readline';

   // Context7 async iteration pattern
   export async function processLineByLine(filePath: string) {
     const rl = readline.createInterface({
       input: fs.createReadStream(filePath),
       crlfDelay: Infinity,
     });

     // for await...of with Symbol.asyncIterator
     for await (const line of rl) {
       // Process each line
       await processLine(line);
     }
   }

   // AbortSignal for cancellation
   export async function fetchWithTimeout(url: string, timeout: number) {
     const controller = new AbortController();
     const id = setTimeout(() => controller.abort(), timeout);

     try {
       const response = await fetch(url, {
         signal: controller.signal,
       });
       return response;
     } finally {
       clearTimeout(id);
     }
   }
   ```

5. **Express App with ES6** (Context7 patterns)
   ```typescript
   // src/app.ts
   import express from 'express';
   import helmet from 'helmet';
   import cors from 'cors';

   // ES6 named exports
   export const app = express();

   // Middleware
   app.use(helmet());
   app.use(cors());
   app.use(express.json());

   // Routes with object property shorthand
   const routes = {
     user: userRouter,
     auth: authRouter,
     health: healthRouter,
   };

   Object.entries(routes).forEach(([path, router]) => {
     app.use(`/api/${path}`, router);
   });
   ```

6. **Controllers with Async/Await**
   ```typescript
   // src/controllers/user.controller.ts
   import { Request, Response, NextFunction } from 'express';

   // ES6 arrow functions with destructuring
   export const getUsers = async (
     req: Request,
     res: Response,
     next: NextFunction
   ) => {
     try {
       const { page = 1, limit = 10 } = req.query; // Destructuring with defaults
       const users = await userService.findAll({ page, limit });
       res.json({ users }); // Object property shorthand
     } catch (error) {
       next(error);
     }
   };
   ```

7. **Testing Setup with Jest**
   - Configure Jest for TypeScript
   - Create test fixtures
   - Add API endpoint tests

8. **Docker Configuration**
   - Multi-stage Dockerfile
   - docker-compose with PostgreSQL/MongoDB
   - Development and production configs

## Context7-Verified Best Practices Applied

From `/nodejs/node` (8,761 snippets, trust 9.1):
- **Async iteration**: for await...of with Symbol.asyncIterator
- **AbortSignal**: Request cancellation support
- **Mixed approach**: rl.on('line') + await once() for performance
- **Event handling**: Proper event emitter patterns
- **Streams**: Async iterators for stream processing

From `/airbnb/javascript` (221 snippets, trust 8.1):
- **ES6 defaults**: Default parameter values
- **Object shorthand**: { lukeSkywalker } instead of { lukeSkywalker: lukeSkywalker }
- **Spread syntax**: { ...original, c: 3 } for object copying
- **Destructuring**: const { a, b } = object
- **Arrow functions**: Consistent use for callbacks

## Expected Output

```
🟢 NODE.JS API SCAFFOLDING
==========================

Project: my-api
Framework: Express + TypeScript
Database: PostgreSQL
ORM: Prisma
Auth: JWT
Testing: Jest

📋 CREATED FILES:
✓ src/index.ts (Entry point with ES6 exports)
✓ src/app.ts (Express configuration with object shorthand)
✓ src/config/index.ts (Config with ES6 defaults)
✓ src/controllers/user.controller.ts (Async handlers)
✓ src/services/user.service.ts (Business logic)
✓ src/middlewares/auth.middleware.ts (JWT verification)
✓ src/middlewares/error.middleware.ts (Error handling)
✓ src/routes/user.routes.ts (API routes)
✓ src/utils/asyncHandler.ts (Async wrapper)
✓ src/utils/streamProcessor.ts (Async iteration)
✓ src/utils/AppError.ts (Custom error class)
✓ prisma/schema.prisma (Database schema)
✓ tests/user.test.ts (API tests)
✓ package.json (Dependencies)
✓ tsconfig.json (TypeScript config)
✓ Dockerfile (Multi-stage build)
✓ docker-compose.yml (Development setup)

🔧 NEXT STEPS:
1. cd my-api
2. npm install (install dependencies)
3. cp .env.example .env (configure environment)
4. docker-compose up -d (start PostgreSQL)
5. npx prisma migrate dev (run migrations)
6. npm run dev (start server)
7. npm test (run tests)

📖 API DOCUMENTATION: http://localhost:3000/api-docs
```

## Validation Checklist

- [ ] Context7 documentation queried for latest patterns
- [ ] All async code uses for await...of where appropriate
- [ ] ES6 syntax used (object shorthand, spread, destructuring)
- [ ] AbortSignal implemented for request cancellation
- [ ] Symbol.asyncIterator used for custom iterators
- [ ] Middleware properly configured
- [ ] JWT authentication implemented
- [ ] Error handling centralized
- [ ] Tests include async patterns
- [ ] Docker configuration is multi-stage
- [ ] TypeScript types properly defined

## Agent Coordination

This command works with:
- **nodejs-backend-engineer**: For implementation details
- **javascript-frontend-engineer**: For ES6 patterns
- **postgresql-expert**: For database schema design
- **docker-containerization-expert**: For containerization
- **test-runner**: For executing tests

## Related Commands

- `/testing:prime` - Setup testing environment
- `/docker:compose-generate` - Generate docker-compose configuration
- `/github:workflow-create` - Create CI/CD workflow

## Error Handling

- Missing project name → Prompt for name
- Invalid framework → Show valid options
- Invalid database type → Show valid options
- No Context7 access → Error with instructions
- Directory exists → Confirm overwrite

## Notes

- Always queries Context7 BEFORE generating code
- Uses latest Node.js async patterns from official docs
- Follows Airbnb JavaScript style guide
- Includes AbortSignal for cancellation support
- Uses Symbol.asyncIterator for custom iterators
- Production-ready with proper error handling and logging
- TypeScript for type safety
- Jest for comprehensive testing
