Node.js Standards¶

Status: 🟢 Active  |  Owner: Frontend/Node Guild

Approved Versions¶

Node.js follows an annual LTS schedule. The enterprise standard tracks the current LTS (even-numbered) release.

Version Management¶

Use .nvmrc (nvm) or .node-version to pin the runtime version per project:

# .nvmrc
22.4.0

In CI, use the pinned version:

- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'
    cache: 'pnpm'

Environment Variables¶

Use environment variables for all configuration. Never hard-code secrets or environment-specific values.

Validate env vars at startup using Zod or a custom schema:

import { z } from 'zod';

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  PORT: z.coerce.number().int().min(1024).default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

export const env = EnvSchema.parse(process.env);

This causes the application to fail fast at startup with a clear error message if a required variable is missing.

Process Management¶

• In Docker/Kubernetes: run Node.js as PID 1 using node directly — not npm start. This ensures SIGTERM is received by the Node process for graceful shutdown.
• Implement graceful shutdown: close the HTTP server, drain in-flight requests, then close database connections.

const server = app.listen(env.PORT);

process.on('SIGTERM', async () => {
  server.close(async () => {
    await db.pool.end();
    process.exit(0);
  });
});

ESM vs CommonJS¶

New projects must use ESM ("type": "module" in package.json). CommonJS is supported for existing projects and tooling compatibility.

// package.json
{
  "type": "module"
}

Pair with "module": "NodeNext" and "moduleResolution": "NodeNext" in tsconfig.json.

Security Considerations¶

• Enable --experimental-permission (Node 22) for file system sandboxing in untrusted workloads — requires Architecture review.
• Never run the Node process as root inside containers.
• Use helmet middleware for HTTP security headers on all Express/Fastify services.
• Keep node_modules out of the Docker image layer — use multi-stage builds.

References¶

• Node.js LTS releases
• Node.js Security Best Practices

Last reviewed: 2025-Q4  |  Owner: Frontend/Node Guild