Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (61 loc) · 4.33 KB

AGENTS.md

File metadata and controls

82 lines (61 loc) · 4.33 KB

Project Identity

Rolldown is a JavaScript/TypeScript bundler written in Rust and TypeScript, designed to be the future bundler for Vite.

  • You are an expert Rust, JavaScript and TypeScript developer.
  • Rolldown's performance is critical for developers and tools built on top of it. As such, it is critical to aim for best possible performance when optimizing Rolldown.

Spec-Driven Development

Design docs live in meta/design/. They capture high-level vision and design intent, giving both humans and AI a shared understanding of what the system should be.

When a design doc exists for a topic, treat it as the source of truth — read it before coding, update it before changing the design. When there isn't one, just code.

  • Format: See meta/design/template.md for the suggested format. Keep it freeform — one concept per file, link between docs, no rigid structure required.
  • Traceability: When implementing or fixing something described in a design doc, link the relevant GitHub issue/PR in commit messages or comments so progress is traceable.

Architecture

Three-Layer Architecture

TypeScript API (/packages/rolldown)
       ↓
NAPI Bindings (crates/rolldown_binding)
       ↓
Rust Core (crates/rolldown)

Repository Structure

  • This is a hybrid Rust and Node.js monorepo managed with pnpm and cargo.
  • crates/: All Rust crates, including the core bundler, NAPI bindings, and builtin plugins.
  • crates/rolldown: The Rust core, implementing the bundler logic.
  • crates/rolldown/tests: Integration tests for the Rust core.
  • crates/rolldown_binding: Defines NAPI bindings to expose Rust functionality to Node.js.
  • crates/rolldown_plugin: Defines the plugin interface for writing plugins in Rust.
  • crates/rolldown_plugin_*: All builtin plugins implemented in Rust.
  • packages/: All Node.js packages, including the main rolldown package.
  • packages/rolldown: The main Node.js package exposing the TypeScript API.
  • packages/rolldown-tests: Test suite for the rolldown package using Vitest.
  • packages/rollup-tests: Compatibility test suite for Rollup plugins.
  • docs/: Documentation site built with VitePress.
  • meta/design/: Design documents. See the "Spec-Driven Development" section above.

Auto-generated or Submodule Files

MANDATORY: NEVER edit these files directly.

  • packages/rolldown/src/binding.js - Based on crates/rolldown_binding, auto-generated by just build-rolldown
  • packages/rolldown/src/binding.d.ts - Based on crates/rolldown_binding, auto-generated by just build-rolldown
  • packages/debug/src/generated/* - Auto-generated code for devtools integration
  • rollup/* - Git submodule for test fixtures
  • test262/* - Git submodule for ECMAScript test suite

Bash commands

IMPORTANT: The project uses just as a task runner. Always prefer just commands over direct npm or cargo commands. Run just --list before using npm or cargo directly.

  • just roll - Builds, lints, and tests everything (Rust + Node.js + repo)
  • just build-rolldown - Builds the rolldown node package, its dependencies and binding binary.
  • just lint - Lints everything (Rust + Node.js + repo)
  • just lint-rust - Performs Rust related linting
  • just lint-node - Performs Node.js related linting
  • just lint-repo - Performs repository related linting
  • just test - Tests everything (Rust + Node.js)
  • just test-rust - Tests Rust crates. Snapshots will be updated automatically if needed.
  • just test-node - Tests Node.js packages
  • just fix - Auto-fixes what can be fixed (Rust + Node.js + repo)
  • just fix-rust - Auto-fixes Rust issues
  • just fix-node - Auto-fixes Node.js issues
  • just fix-repo - Auto-fixes repository issues

Common Pitfalls & Best Practices

  • AGENTS.md is the source of truth. CLAUDE.md is a symlink to it.
  • Check surrounding code for conventions: Before adding new code, always study the existing patterns, naming conventions, and architectural choices in the file and directory you are working in.
  • Break large changes into tracked steps: Decompose substantial work into manageable subtasks. Track progress to prevent scope creep and missed items. Use TodoWrite or similar tools to maintain a checklist.
  • Batch multiple edits: Prefer to batch multiple edits over sequential single edits. Use MultiEdit or similar tools if available.