Cursor Rules for Bun: A Practical Project Template

Bun has different commands, module resolution behavior, and runtime APIs from Node.js. Without a rules file, Cursor will sometimes suggest Node.js patterns in a Bun project: npm install instead of bun install, require() instead of import, or Node.js built-in APIs when a Bun-native equivalent exists.

A Cursor rules file fixes this by telling the assistant exactly which commands to use, which APIs are available in your runtime, and which conventions the project follows. Tools like fenbs keep the decisions that change over time separate from the stable rules, so different coding assistants read the same current constraints without anyone maintaining two documents. For more context on the format, see the Cursor rules examples guide.

Where Cursor reads rules in a Bun project

Cursor reads rules from .cursor/rules/ (a directory of .mdc files) in newer setups, and from a .cursorrules file in the project root for broader compatibility. Both work. Place the Bun-specific rules in .cursor/rules/bun.mdc or in .cursorrules at the project root.

Commit the rules file to your repository. Every developer who opens the project in Cursor uses the same rules, and any AI agent connecting to the project reads the same conventions. If you have rules that apply only to specific file types, the directory format lets you use glob patterns to scope them.

The Bun rules template

Copy this template and edit the sections that do not match your project. Remove sections that do not apply.

## Bun project rules

### Runtime
This project uses Bun, not Node.js.
Use Bun-native APIs when an equivalent exists.
Do not suggest Node.js compatibility shims where a Bun API is available.
Bun version: check package.json packageManager field or .tool-versions.

### Commands
Install: bun install
Add package: bun add <package>
Remove package: bun remove <package>
Run script: bun run <script>
Run file directly: bun <file>.ts
Test: bun test
Build: bun build ./src/index.ts --outdir ./dist --target bun

### Module system
Use ESM (import/export). Do not use require().
File extensions in imports are optional; omit them unless resolving
an ambiguity.
Use bun: namespace imports for Bun runtime APIs:
  import { serve } from "bun";
  import { Database } from "bun:sqlite";
  import { describe, it, expect } from "bun:test";

### TypeScript
Use TypeScript for all source files (.ts, not .js).
tsconfig.json is present; do not duplicate its settings in individual files.
Strict mode is on. Handle all nullable paths.

### Testing
Use Bun's built-in test runner (bun:test).
Test files: *.test.ts alongside source, or in a __tests__ directory.
Name tests descriptively. Use describe() for grouping.
Run bun test before every commit.

### Dependencies
Do not add packages without noting the name and reason.
Prefer packages with Bun compatibility notes or ESM-only builds.
Check for known vulnerabilities before adding a new dependency.

### Review
Summarize changes with a present-tense commit message.
Do not modify generated files or lock files directly.

What each section does

The runtime section is the most important for Bun projects because it directly prevents the Node.js-assumption mistakes that happen without it. Specifying the Bun version avoids suggestions that rely on APIs added after the version you use.

The commands section prevents the assistant from suggesting npm run, yarn test, or Node.js-specific flags. If your project uses a custom build script name, add it here. The module system section prevents require() from appearing in suggested code, which matters for Bun projects that rely on ESM-only packages.

The testing section tells the assistant which test runner to use. Bun has a built-in test runner (bun:test) that mirrors Jest's API. If the assistant does not know you use it, it may suggest Jest configuration or a different assertion library. Naming the assertion pattern avoids this.

Customize for your project type

The template above covers a general Bun project. Adjust it for specific use cases.

• HTTP server: add a section on which router or framework you use (Hono, Elysia, or Bun's built-in serve). Note route naming conventions and error handler patterns.
• CLI tool: add a section on how the entry point is structured, how arguments are parsed, and the target platform for the build output.
• Library package: add a section on the export map structure, which files are included in the published package, and the dual-package pattern if you support both ESM and CJS consumers.
• Monorepo: add a section on which packages exist, how imports between them are structured, and which workspace commands to use.

If you use Cursor for AI-assisted project work beyond coding, the Cursor rules for AI projects guide covers the patterns that apply across project types. For a comparison of Cursor with VS Code for AI-assisted development, see the Cursor vs VS Code guide.

Keeping the rules file accurate as Bun evolves

Bun adds APIs and changes defaults across versions. A rules file written for Bun 1.0 may suggest patterns that work differently in the version your project uses. Update the version reference when you upgrade, and note any API changes that affect how the assistant should write code.

The most practical maintenance step is to update the rules file in the same pull request as the change that triggers it. If you switch to a new router or update your build command, the rules file should change at the same time. A rules file that diverges from the codebase misleads the assistant in exactly the sessions where accuracy matters most.

Specificity matters for Bun rules in particular, because assistants with broad training data may default to Node.js patterns when a Bun instruction is ambiguous. "Use Bun, not Node.js" is clear. "Prefer Bun APIs" is less so, because the assistant has to infer which APIs count. The more concrete the rule, the more reliably the assistant follows it.

When Cursor suggests a Node.js pattern despite the rules file, check whether the file is being read at all (try asking Cursor what runtime the project uses) and whether the specific API you want is named explicitly. Adding the Bun import path, such as import { serve } from "bun", is often more effective than a general instruction to prefer Bun.

What to keep in rules versus in fenbs

The rules file is for stable project facts: the runtime, the commands, the TypeScript configuration, the test runner. These do not change between sessions and apply equally to every developer and AI assistant who opens the project.

Decisions that are still being worked out belong elsewhere. If your team is evaluating two routing libraries, that is not a stable fact to commit to a rules file; it is an open decision. If a package caused a build failure and you agreed to avoid it, that is a lesson worth recording somewhere it will be read before the next session that might suggest it.

How to do this with fenbs

1. Create a free account and add your Bun project.
2. Copy the template above into .cursor/rules/bun.mdc and customize the sections for your setup.
3. Add any architectural decisions that are still in flux as Decisions and rules in fenbs: framework choices under evaluation, dependency policies under discussion.
4. Connect Cursor to fenbs via MCP from Integrations. At the start of a session, Cursor reads both the rules file and the fenbs project context.
5. When an in-flux decision becomes settled, move it into the rules file and record the move in fenbs with the date and reason.