Getting started

This page covers the local development loop for the withastro/astro monorepo. For installing Astro as an end user, run npm create astro@latest and follow https://docs.astro.build/en/getting-started/.

Prerequisites

From CONTRIBUTING.md:

node: "^>=22.12.0"
pnpm: "^10.28.0"

The repo enforces this via the engines field in the root package.json and a preinstall hook (npx only-allow pnpm) that rejects npm install and yarn.

The recommended way to get pnpm is Corepack:

corepack enable

Clone and install

git clone https://github.com/withastro/astro
cd astro
pnpm install        # installs all workspaces
pnpm run build      # builds every package once

pnpm install must be run from the repo root — pnpm workspaces will not resolve correctly otherwise. The first pnpm run build is required because most workspace packages publish their dist/ outputs and the examples link against them.

Two optional but recommended local Git tweaks (from CONTRIBUTING.md):

git config --local blame.ignoreRevsFile .git-blame-ignore-revs
pnpm add -g @pnpm/merge-driver
pnpm dlx npm-merge-driver install --driver-name pnpm-merge-driver \
  --driver "pnpm-merge-driver %A %O %B %P" --files pnpm-lock.yaml

Day-to-day commands

All of these run from the repo root unless noted.

# Watch all packages and rebuild on change (the default dev loop)
pnpm run dev

# One-shot full build of every package
pnpm run build

# Run the example apps against your local Astro source
pnpm --filter @example/minimal run dev

# Lint and format
pnpm run lint
pnpm run format

For package-local commands, use pnpm -C <dir>:

pnpm -C packages/astro build
pnpm -C examples/blog dev

The repo also ships an internal background-process manager:

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

Tests

See how-to-contribute/testing for the full breakdown. Quick reference:

pnpm run test                                 # full test suite (slow)
pnpm run test:match "cli"                     # tests with "cli" in the name
pnpm --filter @astrojs/rss run test           # tests for one package
pnpm run test:e2e                             # Playwright (Firefox)
pnpm run test:e2e:match "View Transitions"

Examples and triage

examples/ and triage/ are linked into the workspace (pnpm-workspace.yaml). Adding a folder under triage/ and running pnpm install is the canonical way to set up a reproduction.

Editor setup

The repo ships per-editor config:

• .vscode/ — recommended VS Code extensions (Astro, Biome, Prettier, ESLint), workspace settings, and launch configs.
• .zed/ — Zed configuration.
• .zed-keymap.json is intentionally absent; settings are minimal.
• .editorconfig — universal line-ending and indent rules.

Formatting is enforced by Biome (biome.jsonc) and Prettier (prettier.config.mjs) — pnpm run format:ci checks these in CI.

Documentation references

• Project repo: https://github.com/withastro/astro
• User-facing docs: https://docs.astro.build/
• LLM-optimized docs: https://docs.astro.build/llms.txt
• Discord: https://astro.build/chat
• AGENTS.md (in the repo root) — coding-agent oriented quick reference, includes the bgproc, agent-browser, and optimize-deps deep dives.