mcpField
N
node-best-practices

node-best-practices

github.com/mcollinaDevelopment2.0k404 installsUpdated 1w ago
Repository

About node-best-practices

A reference skill for building robust, maintainable Node.js applications, covering TypeScript, errors, async code, testing, performance, and operations. It provides workflow guidance and focused rule files with examples.

Key features

  1. 01Node.js TypeScript type-stripping guidance
  2. 02Error handling and async patterns
  3. 03Testing and flaky-test diagnosis
  4. 04Performance profiling and optimization
  5. 05Logging, configuration, and shutdown practices

Use cases

  1. 01Writing TypeScript for Node.js without a build step
  2. 02Designing error handling and graceful shutdown
  3. 03Investigating flaky tests
  4. 04Profiling and improving slow code paths

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mcollina/skills --skill node-best-practices

After installing, type/node-best-practicesin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

rules/
async-patterns.md
caching.md
environment.md
error-handling.md
flaky-tests.md
graceful-shutdown.md
logging.md
modules.md
node-modules-exploration.md
performance.md
profiling.md
streams.md
testing.md
typescript.md
rules/assets/
graceful-server.test.ts
graceful-server.ts

Details

From the project README

When to use

Use this skill whenever you are dealing with Node.js code to obtain domain-specific knowledge for building robust, performant, and maintainable Node.js applications.

TypeScript with Type Stripping

When writing TypeScript for Node.js, use type stripping (Node.js 22.6+) instead of build tools like ts-node or tsx. Type stripping runs TypeScript directly by removing type annotations at runtime without transpilation.

Key requirements for type stripping compatibility:

  • Use import type for type-only imports
  • Use const objects instead of enums
  • Avoid namespaces and parameter properties
  • Use .ts extensions in imports

Minimal example — a valid type-stripped TypeScript file:

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

Run directly with:

node greet.ts

See rules/typescript.md for complete configuration and examples.

Common Workflows

For multi-step processes, follow these high-level sequences before consulting the relevant rule file:

Graceful shutdown: Register signal handlers (SIGTERM/SIGINT) → stop accepting new work → drain in-flight requests → close external connections (DB, cache) → exit with appropriate code. See rules/graceful-shutdown.md.

Error handling: Define a shared error base class → classify errors (operational vs programmer) → add async boundary handlers (process.on('unhandledRejection')) → propagate typed errors through the call stack → log with context before responding or crashing. See rules/error-handling.md.

Diagnosing flaky tests: Isolate the test with --test-only → check for shared state or timer dependencies → inspect async teardown order → add retry logic as a temporary diagnostic step → fix root cause. See rules/flaky-tests.md.

Profiling a slow path: Reproduce under realistic load → capture a CPU profile with --cpu-prof → identify hot functions → check for stream backpressure or unnecessary serialisation → validate improvement with a benchmark. See rules/profiling.md and rules/performance.md.

How to use

Read individual rule files for detailed explanations and code examples:

Comments

Markdown supported