Skip to content

project rulesBackend and APIstypescriptnodejs

TypeScript Node.js Rules

Project rules for TypeScript services on Node.js: strict types, validated boundaries, structured logging and safe async error handling.

npx workspacetemplates add typescript-node-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file22 lines · 1.3 KBFile
# Project rules: TypeScript on Node.js

## Compiler and style
- `strict` true, plus `noUncheckedIndexedAccess` and `noImplicitOverride`. No `any` and no `as` casts to silence errors; use `unknown` and narrow it. ES modules only.
- Prefer small pure functions and explicit return types on exported functions. Keep files under 300 lines.

## Boundaries
- Treat everything from outside as `unknown`: request bodies, queries, env, files, queue messages. Parse with zod and derive types with `z.infer`.
- Load configuration once at startup into a typed, frozen object. Fail fast on a missing variable. Never read `process.env` elsewhere.

## Async and errors
- Every promise is awaited or returned. No floating promises (`@typescript-eslint/no-floating-promises` is on).
- Throw `Error` subclasses with a `cause`. Map them to HTTP codes in one error handler. Never send stack traces to clients.
- Use `AbortSignal` and timeouts for outbound calls. Handle `SIGTERM`: stop accepting requests, drain, then exit.

## Logging and security
- Use pino with structured fields and a request id. Never log tokens, passwords or full request bodies.
- Parameterize every SQL query. Pin dependencies with a lockfile and run `npm audit` in CI.

## Tests
- Vitest, one test file per module, mock only network and time.
- Before finishing run `tsc --noEmit`, `eslint .` and `vitest run`.

What it does

Node services fail in quiet ways: an unhandled rejection, a body nobody validated, a config value that was undefined. These rules make the agent close those gaps by default.

They set the compiler options, how to treat input from outside, how to handle errors and shutdown, and which commands prove a change is finished.

Example

you › Add a POST /subscriptions endpoint

agent › The agent writes a zod schema for the body, a typed service function, a mapped domain error for duplicates, a pino log line with the request id and a Vitest case for the invalid payload.

Questions

Does it require a specific web framework?
No. The rules apply to Express, Fastify, Hono or plain http. Add framework notes if you want more detail.
Why ban type assertions?
A cast hides a mismatch the compiler found. Narrowing or parsing fixes the real problem instead.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Flask Rules

    Project rulespython

    Free
  • Go Service Rules

    Project rulesgo

    Free