node-conventions

Node.js Backend Conventions

This skill consolidates idioms that hold across most Node.js backend projects (Express, Fastify, Koa, plain Node). Follow them when adding code; if a project's CLAUDE.md contradicts a convention here, the project wins.

Project layout

Typical layout:

project-root/
├── package.json
├── tsconfig.json              # if TypeScript
├── src/
│   ├── index.js               # entry point — start server, wire app
│   ├── app.js                 # framework instance (express(), fastify())
│   ├── config.js              # env-var reader (single source)
│   ├── routes/                # route definitions, one file per resource
│   ├── controllers/           # request handlers (or merged into routes)
│   ├── services/              # business logic, framework-agnostic
│   ├── middleware/
│   ├── lib/                   # shared utilities
│   └── db/                    # data access layer
├── test/  OR  __tests__/
└── dist/                      # build output (TS), gitignored

Mirror what exists. If the project uses a flat layout, do not introduce nested layout for one new file.

Configuration

Single config module reading from process.env:

// src/config.js
const requiredEnv = ['DATABASE_URL', 'PORT'];
for (const key of requiredEnv) {
  if (!process.env[key]) throw new Error(`Missing env var: ${key}`);
}

module.exports = {
  port: Number(process.env.PORT),
  databaseUrl: process.env.DATABASE_URL,
  logLevel: process.env.LOG_LEVEL || 'info',
};

Never read process.env from business logic. Always go through config.

Logging

Use the project's existing logger. Detection priority:

1. pino in deps → const logger = require('pino')()
2. winston in deps → use the configured instance
3. bunyan in deps → use the configured instance
4. Otherwise → console.log/console.error is acceptable

Never introduce a new logger as part of feature work without justification in DECISIONS.

Log levels: debug (verbose dev), info (normal flow), warn (recoverable), error (something failed).