Loading…

Nodejs Best Practices

Production-ready Node.js patterns — ESM, native test runner, built-in APIs, async control flow, process management, and security for modern Node.js applications

OpenCodeCodexClaude Code

bash

npx skills add m10rten/typescript-bits --skill nodejs-best-practices

skill.md · 518 lines~3.9k

Node.js Best Practices

Practical, production-ready Node.js patterns for building robust, maintainable server-side applications. Apply these when writing or reviewing Node.js code.

Module System

Always Use ESM

json

{
  "type": "module"
}

Use `import`/`export` syntax throughout — no `require()`.

Import all Node.js built-ins with the `node:` protocol: `import { readFile } from "node:fs"`.

Use explicit file extensions in import paths (`.js`, `.ts`, `.mjs`). Never omit extensions.

Use `import type` / `export type` for type-only imports to keep runtime bundles clean.

Conditional Exports

Use `package.json` `exports` field for dual ESM/CJS distribution or subpath exports:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  }
}

Static Analysis Friendly

Avoid dynamic `import()` in hot paths — prefer static top-level imports.

Use `import.meta.url` instead of `dirname` / `filename`:

import { fileURLToPath } from "node:url";
import { dirname } from "node:path";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Node 21.2+ provides `import.meta.dirname` and `import.meta.filename` directly — no `fileURLToPath` + `dirname` conversion needed.

Native Testing

Use `node:test` and `node:assert`

Prefer Node's built-in test runner over third-party frameworks (Jest, Mocha, Vitest):

import { describe, it, before, after, mock } from "node:test";
import assert from "node:assert/strict";
import { myModule } from "../src/index.js";

describe("myModule", () => {
  it("handles the basic case", () => {
    assert.strictEqual(myModule(1), 2);
  });
});

Test Structure

Use `describe` for grouping, `it` for individual test cases.

Prefer `node:assert/strict` (deepStrictEqual, strictEqual) over the base `node:assert`.

Use edge-case arrays with `for` loops for repetitive tests:

const edgecases = [
  { input: null, expected: "null" },
  { input: undefined, expected: "undefined" },
  { input: "", expected: "empty" },
];
for (const { input, expected } of edgecases) {
  it(`handles ${expected}`, () => {
    assert.strictEqual(myFn(input), expected);
  });
}

Mocking

Use `mock.fn()` and `mock.method()` from `node:test` — avoid external mocking libraries:

import { mock } from "node:test";

const fn = mock.fn((x: number) => x * 2);
assert.strictEqual(fn(3), 6);
assert.strictEqual(fn.mock.calls.length, 1);

Async Patterns

Prefer Promises Over Callbacks

Use `fs.promises` API over `fs.callback` API.

Convert callback-based APIs to promises with `util.promisify` when needed.

Never mix callbacks and promises in the same code path.

Async Iteration

Use `for await...of` for streams and async generators over `.on("data")` / `.on("end")` patterns:

import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";

async function processLines(filePath: string): Promise<void> {
  const rl = createInterface({ input: createReadStream(filePath) });
  for await (const line of rl) {
    // process line
  }
}

Concurrent Execution

// Parallel — no ordering needed
const [a, b] = await Promise.all([fetchA(), fetchB()]);

// Sequential — each depends on prior
const a = await fetchA();
const b = await fetchB(a);

// Race with timeout
const result = await Promise.race([
  fetchData(),
  new Promise<never>((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
]);

Promise.withResolvers() & AbortSignal.timeout()

Node 22+: `Promise.withResolvers()` replaces the deferred pattern:

const { promise, resolve, reject } = Promise.withResolvers();

`AbortSignal.timeout(5000)` is the simplest timeout — simpler than `Promise.race`:

const response = await fetch(url, { signal: AbortSignal.timeout(5000) });

Avoid Unhandled Rejections

Always `await` or `.catch()` promises — never leave them dangling.

process.on("unhandledRejection", (reason) => {
  console.error("Unhandled rejection:", reason);
  process.exit(1);
});

Error Handling

Operational vs Programmer Errors

Type	Examples	Handling
Operational	Network failure, file not found	Recover, retry, or return safe error to user
Programmer	`undefined` access, invalid args	Crash fast — don't recover

Structured Error Classes

export class AppError extends Error {
  readonly code: string;
  readonly statusCode: number;
  readonly context?: Record<string, unknown>;

  constructor(message: string, code: string, statusCode = 500, context?: Record<string, unknown>) {
    super(message);
    this.name = "AppError";
    this.code = code;
    this.statusCode = statusCode;
    this.context = context;
  }
}

Result Type for Expected Failures

Use discriminated union `Result` types for expected failures (network, parsing, validation) and reserve `throw` for programmer errors:

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

const parsed = parseJSON(input);
if (!parsed.ok) {
  return { ok: false, error: new AppError("Invalid JSON", "PARSE_ERROR", 400) };
}

Always Narrow Caught Errors

try {
  await operation();
} catch (err: unknown) {
  if (err instanceof AppError) throw err;
  if (err instanceof SyntaxError) return handleSyntax(err);
  throw new AppError("Unexpected error", "INTERNAL", 500, { cause: err });
}

Process and Environment

Configuration from Environment

Read configuration from `process.env` at startup, not inline.

Validate and coerce environment variables early:

function getEnv(name: string, fallback?: string): string {
  const value = process.env[name] ?? fallback;
  if (value === undefined) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

const config = {
  port: Number(getEnv("PORT", "3000")),
  nodeEnv: getEnv("NODE_ENV", "development"),
};

Exit Codes

Use meaningful exit codes:

Code	Meaning
0	Success
1	General error
2	Misuse of shell builtins
126	Command cannot execute
127	Command not found
130	Terminated by Ctrl+C

Signal Handling

function shutdown(signal: string) {
  console.log(`Received ${signal}, shutting down gracefully...`);
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 10000); // force exit after 10s
}

process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

Structured Logging

Use JSON logging (e.g., `pino`, `bunyan`) over `console.log` in production.

Avoid `console.log` in library code — accept a logger or use the `node:events` pattern.

Node's test runner supports `--test-reporter` for structured output — use it instead of ad-hoc formatting.

Standard Library First

Prefer Built-in APIs Over npm Packages

Need	Built-in	Instead of
HTTP server	`node:http`	express
HTTP/2 server	`node:http2`	spdy
File system	`node:fs` (promises)	fs-extra
SQLite (Node 22.5+)	`node:sqlite`	better-sqlite3
Path manipulation	`node:path`	path-to-regexp
URL parsing	`node:url`	urijs
Command-line parsing	`node:util.parseArgs`	commander, yargs
Assertions / testing	`node:assert`, `node:test`	jest, mocha, chai
Event system	`node:events` (EventEmitter)	eventemitter3
Streaming	`node:stream` (web streams)	through2, pump
Crypto	`node:crypto`	bcrypt (use scrypt)
Subtle Crypto (Web)	`crypto.subtle`	forge, node-webcrypto-ossl
UUID	`node:crypto.randomUUID`	uuid
Environment variables	`process.env`	dotenv (Node 20+ loads .env natively)

When to Add Dependencies

Only when the built-in API is genuinely insufficient.

Prefer zero-dependency libraries when possible.

Evaluate: is the API surface worth the maintenance burden?

Stream and Buffer

Use `Buffer.from()` / `Buffer.alloc()` over the `new Buffer()` constructor.

Use web `ReadableStream` / `WritableStream` APIs in Node 20+ for cross-platform code.

import { Buffer } from "node:buffer";
import { TextEncoder, TextDecoder } from "node:util";

const encoded = new TextEncoder().encode("hello");
const decoded = new TextDecoder().decode(encoded);

File System

Prefer Promises API

import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";

async function readConfig(path: string): Promise<Config> {
  const content = await readFile(path, "utf-8");
  return JSON.parse(content);
}

Avoid Sync APIs in Production Code

`readFileSync`, `writeFileSync`, `existsSync` are acceptable in:

- CLI tools and scripts

- Startup/initialization (before the server starts)

- Build-time tooling

Never use sync calls inside request handlers, event loops, or concurrent operations.

Security

Command Injection Prevention

Never pass unsanitized user input to shell commands:

// ❌ Dangerous
import { exec } from "node:child_process";
exec(`ls ${userInput}`); // userInput could be "; rm -rf /"

// ✅ Safe — use execFile with arguments array
import { execFile } from "node:child_process";
execFile("ls", [userInput]); // arguments are escaped

// ✅ Safe — use spawn with arguments array
import { spawn } from "node:child_process";
spawn("ls", [userInput]);

Path Traversal Prevention

import { resolve, relative } from "node:path";

function safePath(base: string, userPath: string): string {
  const full = resolve(base, userPath);
  if (!full.startsWith(resolve(base))) {
    throw new Error("Path traversal detected");
  }
  return full;
}

Input Validation

Validate all external input at the boundary (network, files, env).

Use structured schemas for complex data.

Never trust `JSON.parse` without validation.

Event Patterns

EventEmitter Conventions

Extend `EventEmitter` for pub/sub objects, not custom listener implementations — unless you need stricter control.

Use `once()` for one-shot listeners, `on()` for persistent ones.

Always provide a `Symbol.dispose` or explicit cleanup method:

import { EventEmitter } from "node:events";

class MyService extends EventEmitter {
  #cleanup: (() => void)[] = [];

  start(): void {
    const listener = (data: unknown) => this.#onData(data);
    someSource.on("data", listener);
    this.#cleanup.push(() => someSource.off("data", listener));
  }

  [Symbol.dispose](): void {
    for (const cleanup of this.#cleanup) cleanup();
    this.removeAllListeners();
  }
}

Memory Leak Prevention

Always remove listeners when done — especially in long-lived processes.

Use the `maxListeners` warning threshold to detect leaks:

import { EventEmitter } from "node:events";
const emitter = new EventEmitter();
emitter.setMaxListeners(20); // silence warning if intentional

Performance Patterns

Avoid Blocking the Event Loop

Offload CPU-intensive work to worker threads via `node:worker_threads`:

import { Worker, parentPort, workerData } from "node:worker_threads";

// Main thread
const worker = new Worker("./cpu-work.js", { workerData: input });
worker.on("message", (result) => console.log(result));

// cpu-work.js — worker thread
parentPort.on("message", (data) => {
  parentPort.postMessage(expensiveComputation(data));
});

Use `SharedArrayBuffer` for zero-copy sharing of large data between threads.

Use `setImmediate()` to break up synchronous work:

function processInBatches(items: big[], batchSize = 1000): void {
  let index = 0;
  function nextBatch(): void {
    const batch = items.slice(index, index + batchSize);
    index += batchSize;
    for (const item of batch) process(item);
    if (index < items.length) setImmediate(nextBatch);
  }
  nextBatch();
}

Pool Resources

Reuse connections, file handles, and workers — don't create/destroy per request:

// ❌ Creates new connection per request
app.get("/data", async () => {
  const conn = await createConnection();
  const result = await conn.query("...");
  await conn.close();
  return result;
});

// ✅ Pooled connection
const pool = new ConnectionPool({ max: 10 });
app.get("/data", async () => {
  const conn = await pool.acquire();
  try {
    return await conn.query("...");
  } finally {
    pool.release(conn);
  }
});

CLI and Tooling

Parse Arguments with `util.parseArgs`

import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  options: {
    output: { type: "string", short: "o", default: "dist" },
    verbose: { type: "boolean", short: "v", default: false },
  },
  allowPositionals: true,
});

Graceful Exit

Clean up resources (file handles, network connections) before exit.

Use `process.on("exit")` for synchronous cleanup only — async cleanup needs `SIGINT`/`SIGTERM` handlers.

Avoid `process.exit()` in library code.

Common Mistakes

Mistake	Fix
Using `require()` instead of `import`	Enable `"type": "module"` in package.json
Omitting file extensions in imports	Always add `.js` extension
Unhandled promise rejections	Always `await` or `.catch()`
Using `fs.readFileSync` in request handlers	Use `fs.promises.readFile` with `await`
Shell injection via template strings in `exec`	Use `execFile` with arguments array
Assuming `err` is always an `Error` instance	Narrow with `instanceof Error` or check shape
Not cleaning up EventEmitter listeners	Track listeners and remove on cleanup/dispose
Using third-party packages for built-in capabilities	Check Node.js docs first — prefer native
Blocking the event loop with CPU-heavy work	Offload to worker threads or chunk with `setImmediate`
Missing `await` in `try/catch`	The caught error may be a rejected promise, not an Error