---
name: nodejs
description: Node.js scripting with ES modules and CommonJS, stdlib-first, npm conventions, and async/await patterns. Use when writing Node.js scripts, .js or .mjs files, working with npm, or building CLI tools.
---

# Node.js

## Module System
- Prefer ES modules (.mjs) for new scripts: `import`/`export` syntax, top-level `await`
- Use CommonJS (.js) when compatibility with older Node.js or existing codebases is needed
- Always specify `"type": "module"` in `package.json` for ES module directories
- Use `.mjs` extension to explicitly opt into ES modules regardless of package.json

## Stdlib First
- Node.js has a RICH standard library - use it before reaching for npm packages
- Built-in modules: `fs`, `path`, `os`, `http`, `https`, `crypto`, `stream`, `events`, `util`, `url`, `querystring`, `child_process`, `readline`, `zlib`, `buffer`, `timers`, `assert`, `dns`, `net`, `tls`
- Only add external packages when stdlib truly can't do the job
- Document WHY each dependency is needed in README.md

## Script Structure
- Start with `#!/usr/bin/env node` shebang
- Use `"use strict"` (CommonJS) or rely on ES module strict mode
- Use `try/catch` around async operations
- Use `process.exit(0)` for success, `process.exit(1)` for failure
- Use `console.error()` for errors, `console.log()` for output
- Parse CLI args with `util.parseArgs()` (Node 18+) or `process.argv`

## Package.json Requirements
- Minimal `package.json` - only what's needed
- Always include: `"name"`, `"version": "1.0.0"`, `"private": true`
- ES modules: `"type": "module"`
- Only add `"dependencies"` when external packages are REQUIRED
- NEVER commit `node_modules/` or `package-lock.json` to templates
- Dependencies are installed by `npm install` at deployment time

## File Operations
- Use `fs/promises` for async file operations
- Use `path.join()` - never string concatenation for paths
- Use `fs.existsSync()` for existence checks
- Stream large files: `fs.createReadStream()` / `fs.createWriteStream()`
- Use `path.resolve()` for absolute paths

## Error Handling
- Always `try/catch` around `await` expressions
- Handle specific error codes: `err.code === 'ENOENT'`, `err.code === 'EACCES'`
- Never use bare `catch {}` - always log or handle the error
- Use `process.on('uncaughtException')` for top-level error handling in long-running scripts

## Safety Rules
- Never `eval()` user input
- Validate file paths before read/write
- Use `path.normalize()` to prevent path traversal
- Never hardcode secrets - use `process.env`
- Hash passwords with `crypto.scrypt()` or `crypto.pbkdf2()`
- Use `child_process.spawn()` with `shell: false`

## Testing
- Run with `--help` and verify exit code 0
- Test with sample data in a `test-data/` directory
- Use `node:assert` for simple assertions
- Smoke test: run script, check exit code, verify output

## Template Integration
- Each template has: `README.md`, `package.json`, `script.mjs` or `script.js`, `smoke-test.mjs`
- NO `node_modules/` - it's in `.gitignore`
- NO `package-lock.json` - generated at install time
- Templates go in `templates/nodejs/<name>/`