Cursor Rules for JavaScript: Modules, Dependencies, and Tests

Cursor rules for JavaScript tell the AI assistant which module format you use, which package manager runs your scripts, how tests are run, and whether it may add or update dependencies on its own. Without these rules, an assistant will write require() in an ES module project or run npm install when your project uses pnpm.

The choices behind those conventions belong in fenbs alongside the tasks. Why did you choose ESM over CommonJS? Why is a particular library preferred? An assistant that reads both the rules file and the project context in fenbs starts each session with the current reasoning, not just the current constraint.

What JavaScript rules should cover

• Module format: ESM (import/export) or CommonJS (require/module.exports), and any file extensions that override the default.
• Package manager: npm, pnpm, yarn, or bun — and the exact commands for install, run, and add.
• Build and test scripts: the exact script names from package.json and how to run them.
• Import conventions: whether to use index files, absolute paths with an alias, or relative paths.
• Dependency policy: whether the AI may add packages and what approval is needed.
• Browser versus Node: if the project targets both, which APIs are available in each environment.

A starting template

# JavaScript project rules

## Module format
- Use ES modules: import/export syntax only.
- File extension is .js (no .mjs unless explicitly required).
- Do not use require() or module.exports.

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

## Scripts (from package.json)
- Build: pnpm run build
- Test: pnpm run test
- Lint: pnpm run lint
- Dev server: pnpm run dev

## Import style
- Use relative paths for local modules.
- Prefer named exports over default exports.

## Dependencies
- Do not add a package without asking.
- Prefer established packages already in use over new ones.

Handling mixed environments

If your project runs in both Node.js and the browser, note which globals are available in each context. An assistant that writes process.env.NODE_ENV in browser-side code will produce a runtime error. A rule that says "no Node.js built-in APIs in files under src/client/" prevents this without requiring you to review every change.

If you use a bundler like Vite or webpack, add the specific behavior your configuration introduces. Rules about path aliases (@/components) or special import suffixes (?raw) can save real debugging time. See Cursor rules for AI projects for how to fit these rules into a larger project setup.

Testing conventions

JavaScript testing setups differ more than most other languages. Vitest, Jest, Mocha, and node:test all coexist in the ecosystem, and the differences between them are significant enough to break a test file copied from one project to another. Add the test runner, the config file location, and any test utilities your project standardizes.

## Tests
- Test runner: Vitest
- Run all tests: pnpm test
- Run a single file: pnpm test <filename>
- Test files live next to the code they test with a .test.js extension.
- Do not use Jest APIs (describe.each, jest.fn); use Vitest equivalents.
- Mock dependencies with vi.mock(), not jest.mock().

Async error handling

Unhandled promise rejections are one of the most common causes of silent failures in JavaScript applications. Add an explicit rule about how async errors should be handled in your project. If your project uses a global error handler, say so. If every async function must be wrapped in try/catch, state that. If the project uses a Result type or an error boundary pattern, describe where it is used.

An assistant that ignores promise rejections will produce code that works in the happy path but fails silently in production when a network request errors or an API returns an unexpected response. A specific error handling rule prevents this class of bug at the code generation step rather than catching it in code review.

The decisions that make templates project-specific

Every JavaScript project uses a slightly different combination of tools and conventions. The template above captures structure; your project's rules should capture the specifics. Replace pnpm with the package manager you actually use. Replace the script names with the real names from your package.json.

The reasons behind those specifics belong in fenbs. Why does the project use pnpm instead of npm? Why are default exports avoided? Recording those decisions in fenbs keeps them visible to everyone, not just the developer who originally made the choice.

How to set up JavaScript rules with fenbs

1. Create a free account and add your project to fenbs. Record the key choices as Decisions: module format, package manager, any architecture decisions about folder structure.
2. Add the template above to your project's .cursor/rules/ directory and replace the placeholders with your actual script names and package manager.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context at the start of each session.
4. When you migrate a tool or change a convention, update the Decision in fenbs and the rules file in the same change so they stay in sync.

What to watch for

JavaScript projects often have multiple configuration files — .eslintrc, .prettierrc, tsconfig.json, vite.config.js. An assistant that edits these without understanding how they interact can break the whole development environment. Add a rule that requires it to ask before changing any configuration file at the root of the project.

If your project uses TypeScript even though the keyword "JavaScript" appears in the rules, note that explicitly. Many JavaScript projects are compiled TypeScript. A rule that says "this is a TypeScript project despite the .js output" prevents an assistant from generating untyped code.

Lock files — package-lock.json, pnpm-lock.yaml, yarn.lock — should not be edited manually. Add an explicit rule that the lock file is managed by the package manager only. An assistant that edits a lock file to resolve a conflict can corrupt the dependency graph in ways that are difficult to recover from without a clean install. The right answer when a lock file has a conflict is to let the package manager regenerate it.