# Node.js

> ContextOS skill for Node.js

- Skill: `kok-o/node-js-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kok-o/node-js-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kok-o/node-js-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kok-o (https://skillmd.com/u/kok-o)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kok-o/node-js-2

---


# Node.js

## Overview

Production-grade Node.js runtime and server standard. Enforces async event loop non-blocking hygiene, graceful shutdown, structured JSON logging with correlation IDs, and unhandled rejection guards.

## When to Use

Activate when developing Node.js HTTP servers, Express/Fastify APIs, background workers, CLI tools, or stream-based data pipelines.

## Negative Constraints (What NOT to Do)

1. **NEVER execute synchronous filesystem/crypto calls in request handlers (`fs.readFileSync`)**: Always use async promises (`fs.promises.*`) to avoid blocking the event loop.
2. **NEVER leave uncaught promise rejections**: Every async route must use `express-async-errors` or wrap operations in try/catch calling `next(err)`.
3. **NEVER buffer large files/payloads entirely in memory (`fs.readFile`)**: Always use Streams or Pipelines (`stream.pipeline`) for processing large files.
4. **NEVER store in-memory session or user state on a single process instance**: Use Redis or an external state store to allow multi-instance scaling.
5. **NEVER ignore `SIGTERM` / `SIGINT` shutdown signals**: Always implement graceful shutdown to close open DB pools and drain active HTTP connections.

## Rules & Patterns

## Architecture

- **Layered architecture**: Routes → Controllers → Services → Repositories
- **Dependency injection** — don't import dependencies directly in services
- **Config from environment** — never hardcode secrets, use env variables
- **Graceful shutdown** — handle SIGTERM, close connections, drain requests

## Error Handling

- **Never swallow errors** — always handle or re-throw
- **Custom error classes** — extend Error with HTTP status codes
- **Global error handler** — catch unhandled rejections and uncaught exceptions
- **Structured logging** — JSON logs with request ID, timestamp, level

```typescript
class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public code: string = 'INTERNAL_ERROR'
  ) {
    super(message);
    this.name = 'AppError';
  }
}
```

## API Design

- **RESTful conventions** — GET (read), POST (create), PUT (full update), PATCH (partial), DELETE
- **Consistent response format** — `{ data, error, pagination }`
- **Validation at the edge** — validate request body/params with Zod or Joi
- **Rate limiting** — protect against abuse
- **CORS** — configure explicitly, never use `*` in production

## Security

- **Helmet.js** — security headers
- **Input validation** — never trust client input
- **SQL injection** — always use parameterized queries
- **XSS** — sanitize output, use Content-Security-Policy
- **Authentication** — JWT with short expiry + refresh tokens
- **Secrets** — environment variables, never in code

## Database

- **Connection pooling** — don't create connections per request
- **Migrations** — version-controlled schema changes
- **Transactions** — for multi-step operations
- **Indexes** — add indexes for frequently queried columns

## Performance

- **Async/await** — never block the event loop
- **Streaming** — for large files and data sets
- **Caching** — Redis for frequently accessed data
- **Clustering** — use PM2 or cluster module for multi-core

## Testing

- **Unit tests** — services and utilities
- **Integration tests** — API endpoints with test database
- **Test isolation** — each test should be independent
- **Fixtures** — use factories, not shared state

## File Structure

```
src/
├── config/          # Configuration
├── modules/         # Feature modules
│   └── users/
│       ├── users.controller.ts
│       ├── users.service.ts
│       ├── users.repository.ts
│       ├── users.routes.ts
│       ├── users.types.ts
│       └── users.test.ts
├── shared/          # Shared utilities
│   ├── middleware/
│   ├── errors/
│   └── utils/
├── types/           # Global types
└── app.ts           # App entry point
```


## Code Examples

See `EXAMPLES.md` for detailed code examples.

## Validation Checklist

What to verify during the review phase before completing the task.

## Common Mistakes

Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.

## Integration Notes

How this skill interacts with other skills.