Cursor Rules for Node.js: Runtime, Packages, and Tests

Cursor rules for Node.js tell the AI assistant which Node.js version the project requires, which package manager runs the scripts, how async code should be structured, and which test runner to use. A Node.js project using Node 22 and pnpm needs different rules from one running on Node 18 with npm, and an assistant without those rules will make plausible guesses that may break in production.

The operational decisions behind those choices — why Node 20 LTS was chosen, why the project uses a specific async pattern, which packages are approved for production use — belong in fenbs as Decisions, where they stay visible to every assistant without being buried in the rules file.

What Node.js rules should cover

• Runtime version: the minimum Node.js version and any engine constraints from package.json.
• Package manager: npm, pnpm, yarn, or bun, and the exact commands for each workflow.
• Module format: ESM, CommonJS, or both, and any bundler that transforms the output.
• Async patterns: promises versus async/await, whether callbacks are used in legacy code, and how errors from async functions are handled.
• Environment variables: which variables are required, where they are loaded from, and whether the project uses dotenv or a config library.
• Test runner and commands: Jest, Vitest, node:test, Mocha, or another runner, and the exact commands for unit and integration tests.

A starting template

# Node.js project rules

## Runtime
- Minimum Node.js version: 20 LTS
- Do not use APIs that are not available in Node 20.

## Package manager
- Use pnpm. Do not use npm or yarn commands.
- Install: pnpm install
- Add a dependency: ask before running pnpm add
- Run a script: pnpm run <script>

## Module format
- ES modules throughout (type: "module" in package.json).
- Use import/export, not require/module.exports.

## Async code
- Use async/await for all asynchronous operations.
- Always handle promise rejections: try/catch or .catch().
- Do not use callbacks for new code; wrap callback-based APIs with promisify.

## Environment variables
- Load from .env using the dotenv package.
- Required variables are documented in .env.example.
- Do not hardcode values that belong in environment variables.

## Tests
- Run: pnpm run test
- Watch mode: pnpm run test:watch
- Do not modify test fixtures in __fixtures__/ without asking.

Runtime version rules in practice

Node.js version constraints matter more than most developers expect. A project that specifies "engines": { "node": ">=20" } in package.json is using APIs that may not exist in Node 18. An assistant without a runtime version rule will use whichever APIs it knows about, potentially including ones that are not available in the version your deployment environment runs.

If your project targets multiple deployment environments with different Node.js versions — say, a CI environment running Node 20 and a production environment still on Node 18 — state both in the rules and note which is the actual constraint. See Cursor CLI for how Cursor interacts with the terminal when running Node commands.

Operational decisions and fenbs

Why does the project use Node 20 instead of the latest version? Why is pnpm used instead of npm? Why was the async pattern standardized on async/await instead of a reactive library? Those decisions were made for reasons that the package.json alone does not explain.

Recording them in fenbs as Decisions means the next assistant can read the reasoning, not just the outcome. When a constraint changes — a runtime upgrade, a package manager migration — a new Decision captures the change and its reason alongside the tasks that drove it.

How to set up Node.js rules with fenbs

1. Create a free account and add your Node.js project to fenbs. Record the operational decisions: Node.js version constraint, package manager choice, deployment environment constraints.
2. Add the template above to your project's .cursor/rules/ directory and update it with your actual Node.js version, package manager commands, and test runner.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context at session start, including any Decisions about the runtime environment.
4. When the project upgrades Node.js, changes its package manager, or adopts a new test runner, update the Decision in fenbs and the rules file in the same change.

Logging and observability conventions

Node.js projects vary in how they handle logging. Some use console.log in development and a structured logger like Pino or Winston in production. Some route all logs through a centralized logger module. An assistant without logging rules will use whatever comes to hand, mixing console.log calls into code that uses a structured logger, or logging sensitive data that should be excluded.

Add a logging rule that names the logger and its import path. State which log levels are used in which contexts and what must never be logged — passwords, tokens, full request bodies with user data. A short logging section in the rules file prevents the most common observability mistakes at the code generation step.

Security rules for Node.js

Node.js applications face specific security risks that an AI assistant needs to know about. Command injection is possible if the project ever passes user input to child_process functions. Path traversal is possible if the project reads files using paths built from user input. SQL injection is possible if queries are built by string concatenation.

Write the security rules as explicit prohibitions: do not pass user input to child_process without sanitization, do not build file paths from user input, do not concatenate user input into SQL queries. An assistant that sees these rules as explicit constraints will not produce vulnerable code even if the surrounding code does not make the risk obvious.

What to watch for

Node.js projects often use different runtime versions across development, CI, and production. If these differ, say so explicitly. An assistant that knows the production runtime is Node 20 but development uses Node 22 will avoid using Node 22-only APIs in production code.

Environment variable handling is a common source of security issues. Make the rules clear: do not hardcode secrets, do not commit .env files, do not log environment variable values. These rules are short enough to include directly in the rules file and important enough that the assistant should not have to infer them.