Development workflow

The day-to-day loop for contributing to withastro/astro.

Setup

See overview/getting-started for prerequisites (Node ≥ 22.12, pnpm ≥ 10.28). Always run pnpm install from the repo root.

Build dependencies

pnpm-workspace.yaml keeps every package in packages/, packages/integrations/, packages/language-tools/, packages/markdown/, plus examples/, triage/, smoke/, scripts/, and benchmark/ linked together. Examples and tests import their packages by their npm name (astro, @astrojs/react, …) and pnpm resolves them to the local dist/ output.

pnpm run build       # one-shot build of every published package
pnpm run dev         # Turbo runs every package's `dev` script in watch mode
pnpm run build:ci    # build path used by CI (no incremental cache)

The dev script is the daily driver: it watches packages/astro/src/, rebuilds dist/ on change, and the linked examples pick the change up immediately.

Working in a single package

Use pnpm -C for package-local commands:

pnpm -C packages/astro build
pnpm -C packages/integrations/vercel test
pnpm -C examples/blog dev

pnpm --filter is also supported but -C is faster for one-off paths.

Branches

• main — active development, where every PR lands. Periodically put into prerelease mode (changeset pre enter next).
• latest — auto-updated to the most recent stable release. create-astro reads from this branch.

Releases

Releases are automated. The Changesets bot maintains a [ci] release PR that aggregates pending .changeset/*.md files. When a maintainer merges that PR, every affected package is published.

Snapshot releases for testing PRs are triggered with the pr preview label. The result is a next--<keyword> dist-tag installable via npm install astro@next--<keyword>.

Prereleases (astro@next) are produced when the repo is in changeset prerelease mode (changeset pre enter next). Only L3+ maintainers can enter or exit prerelease mode. While in prerelease mode, the manual astro@latest release procedure in CONTRIBUTING.md ("Releasing astro@latest while in prerelease mode") applies.

Adding an export

Adding any export to packages/astro/package.json requires updating both maps:

• "exports" (monorepo view)
• "publishConfig.exports" (npm view) — only for public entries; internal entries should be ./_internal/* and not appear here.

packages/astro/test/exports.test.ts will fail if the maps drift apart after stripping _internal/*.

Changesets

pnpm exec changeset

The wizard asks which packages changed and what bump (patch/minor/major). It writes a markdown file under .changeset/. Commit it with your code change.

Use major only for breaking changes (and only with maintainer approval — Astro does breaking changes intentionally and infrequently).

CI

The main workflow is .github/workflows/ci.yml. The most relevant sibling workflows:

Workflow	Purpose
ci.yml	Build, lint, test, types matrix on every PR.
format.yml	Auto-formats main after a merge.
release.yml	Creates/updates the changeset release PR; publishes to npm on merge.
preview-release.yml	Snapshot release on pr preview label.
continuous_benchmark.yml	Tracks performance regressions on main.
examples-deploy.yml	Deploys examples to a preview environment.
sync-examples.yml	Mirrors examples into the withastro/astro.new repo.
issue-needs-repro.yml	Auto-closes needs repro issues after 3 days.
issue-triage.yml	Auto-labels and routes new issues.
merge-main-to-next.yml	Keeps the next prerelease branch in sync.

The label pr preview triggers preview-release.yml. The !bench PR comment triggers continuous_benchmark.yml.

Related pages

• Testing
• Debugging
• Tooling