Tooling

Internal and external tools used to build, test, lint, and ship Astro.

Package management: pnpm

The repo enforces pnpm via preinstall: npx only-allow pnpm. The version is pinned in package.json ("packageManager": "pnpm@10.30.3").

Notable pnpm-workspace.yaml settings:

• preferWorkspacePackages: true, linkWorkspacePackages: true — anything published from the monorepo is linked rather than installed from npm.
• saveWorkspaceProtocol: false — examples don't get the workspace: prefix in their package.json, so the published example versions remain valid.
• autoInstallPeers: false.
• publicHoistPattern — hoists @webcomponents/template-shadowroot, *lit*, and @astrojs/db so they resolve from the project root (each has a known reason documented inline in the YAML).
• minimumReleaseAge: 4320 minutes (3 days) — packages must have been on npm for 3 days before pnpm will install them. Includes carve-outs for security updates.
• peerDependencyRules.allowAny: ['astro', 'vite'] — tolerates wide peer ranges for these.
• onlyBuiltDependencies — explicit allowlist of native postinstall scripts (esbuild, workerd, sharp, @parcel/watcher, keytar, @vscode/vsce-sign, @biomejs/biome).
• patchedDependencies — @changesets/get-github-info@0.7.0 is patched in patches/.

Root package.json pnpm.overrides:

• picomatch@<4 → ^2.3.2
• vite@^7 → ^7.3.2

Build orchestration: Turbo

turbo.json defines the task graph:

• build → ^build (depends on upstream packages).
• dev is persistent: true and disables caching.
• test, test:e2e, test:hosted, lint, typecheck:tests are declared with explicit input globs to maximize cache hits.

Affected-only test runs are dispatched by scripts/turbo-run-affected.js (used by the root test:astro and test:integrations scripts).

Internal CLI: astro-scripts

scripts/ is itself a workspace package (@astrojs/scripts-style internal name; see scripts/package.json). It exposes:

• astro-scripts build — build a single TypeScript package via esbuild + tsc.
• astro-scripts dev — watch-mode build for pnpm dev.
• astro-scripts prebuild — inline string conversion of the client hydration shims (src/runtime/client/{idle,load,media,only,visible}.ts) so they ship as inline JavaScript strings.
• astro-scripts test — node:test runner with --match, --only, --parallel, --timeout, --watch flags. Source: scripts/cmd/test.js.
• astro-scripts smoke — example/docs build verification.

scripts/deps/update-example-versions.js rewrites example package versions during release.

Linting and formatting

• Biome (biome.jsonc) — primary formatter and import-organizer. pnpm run format:code writes, pnpm run format:code:ci checks. pnpm run lint:fix runs biome lint --write --unsafe.
• Prettier (prettier.config.mjs) — covers files Biome doesn't (Markdown, MDX, YAML). The astro-aware plugin prettier-plugin-astro is enabled.
• ESLint (eslint.config.js) — TypeScript-eslint plus eslint-plugin-regexp. Mostly suggestion-level rules.
• knip (knip.js) — detects unused exports, files, and dependencies. Runs as part of pnpm run lint.
• publint (pnpm run publint) — validates publishable packages' npm exports.

.prettierignore and biome.jsonc's ignore lists exclude dist/, node_modules/, .changeset/, and similar.

Background processes: bgproc

bgproc is an external dev-experience helper installed as a dev dependency. It runs commands as named, persistent background processes, captures their logs, and waits for ports.

pnpm exec bgproc start -n devserver --wait-for-port 10 --force -- pnpm -C examples/minimal dev
pnpm exec bgproc logs -n devserver
pnpm exec bgproc stop -n devserver
pnpm exec bgproc list

Per AGENTS.md, this is the preferred way for AI agents (and humans) to manage long-running dev/preview servers — do not background with & if bgproc will do it.

Browser automation: agent-browser

agent-browser is not a dependency of the monorepo; it is expected to be installed globally (npm install -g agent-browser && agent-browser install). It is the recommended way to validate HMR and UI behavior because curl cannot drive the WebSocket-based HMR protocol.

Workflow per AGENTS.md:

1. agent-browser open <url>
2. agent-browser snapshot -i
3. agent-browser click @e1 / fill @e2 "text"
4. Re-snapshot after every change.

Compiler

The Astro .astro compiler lives in withastro/compiler (Go, compiled to WASM). It's consumed via the @astrojs/compiler npm package. To test compiler changes locally, the recommended pattern (per CONTRIBUTING.md) is a pnpm.overrides entry pointing to a local compiler checkout, then re-running pnpm install.

Flue (private)

@flue/cli and @flue/client appear in devDependencies and pnpm-workspace.yaml's minimumReleaseAgeExclude list. These are internal Astro tooling under active development; there is a .flue/ directory at the repo root.

CI/CD

GitHub Actions workflows live under .github/workflows/. The most consequential:

Workflow	Trigger	Action
ci.yml	PR + push to main	Lint, build, test, e2e (matrix)
release.yml	Push to main with changesets	Open/update the [ci] release PR; publish on merge
preview-release.yml	pr preview label	Snapshot publish
continuous_benchmark.yml	!bench comment	Run benchmarks on PR + main, post comment
format.yml	Push to main	Auto-format and push back
merge-main-to-next.yml	Schedule	Keep next branch in sync
sync-examples.yml	Push to main	Mirror examples to astro.new
examples-deploy.yml	Push to main	Deploy preview of examples
issue-needs-repro.yml, issue-close-cleanup.yml, issue-triage.yml, issue-wontfix.yml, congrats.yml	Issue events	Bot-driven triage

Renovate / dependency hygiene

pnpm-workspace.yaml includes a minimumReleaseAgeExclude list that's curated for security updates (e.g. fast-xml-parser@5.3.8, svelte@5.53.5, rollup@4.59.0, undici@7.24.0, picomatch@4.0.4). When Renovate opens an upgrade PR for one of these versions, the entry can be added here to bypass the 3-day cooldown.

Editor configs

• .vscode/settings.json and .vscode/extensions.json — recommended workspace setup.
• .zed/settings.json — Zed.
• .gitpod.yml and .gitpod/ — Gitpod template.
• .devcontainer/ — GitHub Codespaces / Dev Containers — multiple variants for tutorial integrations.
• .editorconfig — project-wide indentation and line-ending policy.

Related pages

• Development workflow
• Testing
• Debugging