nodejs-development
Develop, test, and package server-side Node.js applications and CLI utilities using modern ES Modules and runtime APIs. Use when building Node.js backend services, implementing streaming I/O with stre
SKILL.mdskills/nodejs-development/SKILL.md
GitHubModern Node.js Development
Node.js provides an asynchronous, event-driven JavaScript runtime for server-side services and CLI tools. Modern Node.js development (Node 18+, 20+, 22+) emphasizes standard ES Modules (ESM), built-in APIs (Fetch, Test Runner, Streams), strict error boundaries, and non-blocking I/O.
Core Rules
- Use
"type": "module"inpackage.json: Adopt native ES Modules across the project. - Never block the Event Loop: Do not run synchronous file methods (
fs.readFileSync) or CPU-heavy encryption loops in request handlers. - Always use
stream.pipelinefor stream piping: Never use raw.pipe()in production, as it fails to properly forward errors and can cause memory leaks. - Register shutdown signals (
SIGTERM,SIGINT): Gracefully close open sockets, database connections, and background workers when containers shut down. - Handle process-level error events: Always monitor
unhandledRejectionanduncaughtExceptionto log errors and exit gracefully.
1. Native ES Modules and package.json
{
"name": "my-service",
"version": "1.0.0",
"type": "module",
"engines": {
"node": ">=20.0.0"
},
"main": "./src/index.js",
"bin": {
"my-cli": "./src/cli.js"
},
"scripts": {
"start": "node src/index.js",
"test": "node --test tests/**/*.test.js"
}
}
Importing built-in modules using the standard node: protocol prefix:
import { readFile } from 'node:fs/promises';
import { createServer } from 'node:http';
import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
2. High-Performance Streaming with pipeline
Safely stream large files without loading them entirely into heap memory:
import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
export async function compressFile(sourcePath, destPath) {
try {
await pipeline(
createReadStream(sourcePath),
createGzip(),
createWriteStream(destPath)
);
console.log(`Successfully compressed ${sourcePath} -> ${destPath}`);
} catch (err) {
console.error('Pipeline compression failed:', err);
throw err; // Pipeline automatically cleans up all streams on error!
}
}
3. Graceful Shutdown & Signal Handling
In containerized environments (Docker, Kubernetes), applications receive SIGTERM when scaling down:
import { createServer } from 'node:http';
const server = createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ status: 'healthy' }));
});
server.listen(3000, () => {
console.log('Server running on port 3000');
});
function gracefulShutdown(signal) {
console.log(`Received ${signal}. Closing HTTP server...`);
server.close((err) => {
if (err) {
console.error('Error during shutdown:', err);
process.exit(1);
}
console.log('Server closed. Releasing resources...');
// Close database pools, message brokers, etc.
process.exit(0);
});
// Force exit if hanging beyond 10 seconds
setTimeout(() => {
console.error('Forced shutdown due to timeout.');
process.exit(1);
}, 10000).unref();
}
process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));
4. Built-in Test Runner (Node 18+)
No external framework needed for fast, zero-dependency unit tests:
import { test, describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { parseConfig } from '../src/config.js';
describe('Config Parser', () => {
it('parses valid port and host', () => {
const config = parseConfig({ PORT: '8080', HOST: '0.0.0.0' });
assert.equal(config.port, 8080);
assert.equal(config.host, '0.0.0.0');
});
it('rejects non-numeric port with TypeError', () => {
assert.throws(
() => parseConfig({ PORT: 'invalid' }),
{ name: 'TypeError', message: /Invalid port/ }
);
});
});
5. Common Mistakes and Anti-Patterns
| Anti-Pattern | Risk | Correct Practice |
|---|---|---|
readable.pipe(writable) |
Memory leak and dangling file descriptors if an error occurs | Use await pipeline(readable, writable) |
fs.readFileSync() in server routes |
Stalls all other HTTP requests on the event loop | Use await fs.promises.readFile() |
Silent process.exit(0) on error |
Obscures crashes in monitoring tools | Exit with non-zero code: process.exit(1) |
Omission of "node:" import prefix |
Risk of importing malicious npm packages squatting core names | Always import as node:fs, node:path, etc. |
6. Verification Checklist
-
"type": "module"set inpackage.json. - Core imports use
node:prefix. - Stream pipelines use
node:stream/promises. - Graceful shutdown handlers attached to
SIGTERM/SIGINT. - Tests pass via
node --test.