Develop, Build, and Test

Astro development has two related audiences in this repository: application authors running a project locally, and contributors validating package behavior across the monorepo. The public workflow starts with an Astro project and the development server described in the docs: edit files, run the configured development script, and use the browser preview while Astro watches the source tree. The repository workflow expands that same loop into package builds, example builds, fixture builds, integration tests, type checks, linting, and end-to-end checks coordinated from the root workspace.

Sources: README.md, package.json

Purpose and Scope

Use this page when you need to understand how local development, production builds, examples, and tests fit together in the Astro repository. The root package declares the workspace as private, pins the project to pnpm, requires a modern Node runtime, and centralizes most contributor commands under scripts. That means contributors should treat package-level tasks as part of a larger workspace pipeline rather than as isolated commands. Application authors can still use the familiar project commands, while repository contributors usually run filtered Turbo or package-specific scripts to limit work to the packages they changed.

Sources: package.json

The official development flow is intentionally simple for a user-created site: open the project in an editor, run the starter’s development script, and visit the local preview. In the repository, the same idea is represented by fixtures and examples that exercise realistic Astro projects. A fixture can be small, but it still captures a contract: assets must build, dynamic routes must emit files correctly, read-only files should not break builds, and concurrent builds should remain stable. These fixtures are not tutorials; they are compact reproductions of behavior that the test suite protects.

Sources: packages/astro/test/fixtures/build-assets/package.json, packages/astro/test/fixtures/build-concurrency/package.json, packages/astro/test/fixtures/build-readonly-file/package.json, packages/astro/test/fixtures/dynamic-route-build-file/package.json

Relevant Source Files

• package.json - Defines root workspace scripts for build, development, testing, smoke checks, type checking, linting, benchmarks, release, and pnpm enforcement.
• README.md - Establishes the public project entry point, recommended installation command, manual install option, documentation link, and contributor support path.
• packages/integrations/svelte/test/fixtures/prop-types/types/testing-library/Component.ts - Shows a framework-specific component testing fixture using Svelte Testing Library against a Svelte component.
• packages/astro/test/fixtures/static-build/src/components/Nav/index.jsx - Provides a static build fixture component using Preact, CSS modules, internal links, external links, and inline SVG markup.
• packages/astro/test/fixtures/build-assets/package.json - Declares a build fixture that depends on Astro, Preact, and the Preact integration to exercise asset and framework build behavior.
• packages/astro/test/fixtures/build-concurrency/package.json - Declares a minimal build fixture focused on concurrent build behavior with only the Astro workspace dependency.
• packages/astro/test/fixtures/build-readonly-file/package.json - Declares a fixture for build behavior when files may be read-only or constrained by file-system permissions.
• packages/astro/test/fixtures/dynamic-route-build-file/package.json - Declares a fixture for dynamic route build output behavior with the Astro workspace dependency.

Core Commands

For application development, the command users normally see is the project script that runs Astro’s dev server. The docs describe this as the moment when the site becomes available in the browser and Astro listens for live changes, especially in the source directory. In the monorepo, the root development script runs Turbo in parallel with high concurrency and filters the work to Astro, create-astro, integration packages, and benchmark packages. This distinction matters: a site author starts one dev server, while a contributor may start many package watch tasks that serve package development rather than a single website preview.

Sources: package.json

Production validation starts with the root build scripts. The normal build script asks Turbo to build the main Astro package, the project generator, Astro integration packages, the VS Code tooling package, and benchmark packages. CI has a related build script, plus a no-cache variant that uses recursive pnpm filters instead of the cached Turbo path. Example projects have their own build script and smoke-test command. When a change touches public behavior, use the narrowest command that proves the behavior first, then run the broader build or smoke target before opening a pull request.

Sources: package.json

Fixture-Based Build Coverage

The build fixtures show how Astro protects different categories of output behavior. The asset fixture depends on Astro, Preact, and the Preact integration, so it can exercise a project that combines Astro pages with framework components and bundled assets. The static build navigation component imports Preact, imports a Sass module, renders internal navigation links, and includes SVG icons. That combination is useful because a successful static build must handle JSX, CSS module class names, framework integration, local styles, links, and SVG markup without requiring a server runtime.

Sources: packages/astro/test/fixtures/build-assets/package.json, packages/astro/test/fixtures/static-build/src/components/Nav/index.jsx

Other fixtures narrow the target even further. The concurrency fixture depends only on the workspace Astro package, making it a focused reproduction for build scheduling rather than framework integration. The read-only file fixture is similarly minimal, which helps isolate file-system behavior from application complexity. The dynamic route build-file fixture also keeps dependencies small while representing route generation output. This pattern is common in test suites: complex fixtures prove integration across several subsystems, while minimal fixtures make failures easier to diagnose when a single build contract regresses.

Sources: packages/astro/test/fixtures/build-concurrency/package.json, packages/astro/test/fixtures/build-readonly-file/package.json, packages/astro/test/fixtures/dynamic-route-build-file/package.json

Testing Workflow

The root test script chains Astro package tests, integration tests, and language-tools tests. More specific scripts route to package directories or filtered Turbo runs: Astro unit, CLI, type, match, integration, and end-to-end tests are separate entry points, while integration and language-tool tests are filtered by workspace package. End-to-end scripts install the Firefox Playwright browser before running the relevant package tests. This layout lets contributors choose between a broad confidence pass and a targeted loop, which is important in a repository with packages for the framework core, integrations, project creation, language services, and examples.

Sources: package.json

Astro’s docs recommend Vitest for unit and integration tests because it is Vite-native and supports ESM, TypeScript, and JSX. The repository evidence also shows framework-specific testing through a Svelte fixture that imports a component and renders it with Svelte Testing Library. This is a useful reminder that Astro testing is not limited to Astro files. Since Astro projects can contain framework islands, the test strategy often combines Astro-level build or routing fixtures with direct framework component tests. Choose the layer that matches the risk: render the framework component for prop and UI behavior, then build an Astro fixture for integration behavior.

Sources: packages/integrations/svelte/test/fixtures/prop-types/types/testing-library/Component.ts

Recommended Contributor Flow

A practical local loop begins by installing with pnpm, because the root preinstall script enforces pnpm and the package manager field pins the expected version. After making a change, run the smallest relevant test first: a package unit test for local logic, a fixture test for build output, a type test for public typings, or an integration test for framework behavior. Then run formatting, linting, and type checking if your change touches shared code. For behavior that can affect examples or documentation starters, run the example build or smoke test before relying on a full CI run to catch regressions.

Sources: package.json, README.md

When diagnosing a failure, map the failing command back to the fixture or script purpose. A failure in the asset fixture may involve JSX, CSS modules, the Preact integration, or bundling. A concurrency fixture failure is more likely about scheduling or shared build state. A read-only file failure points toward write behavior and file-system assumptions. A dynamic route build-file failure points toward route generation and emitted output. This source-to-code mapping prevents over-broad debugging and helps you decide whether the fix belongs in core build logic, an integration package, or a test fixture expectation.

Sources: packages/astro/test/fixtures/static-build/src/components/Nav/index.jsx, packages/astro/test/fixtures/build-assets/package.json, packages/astro/test/fixtures/build-concurrency/package.json, packages/astro/test/fixtures/build-readonly-file/package.json, packages/astro/test/fixtures/dynamic-route-build-file/package.json

Command Reference

Task	Root entry point	Use when
Develop packages	pnpm run dev	You need workspace package dev tasks running in parallel.
Build release packages	pnpm run build	You need a broad local production build for core packages and integrations.
Build examples	pnpm run build:examples	You need to validate official examples.
Run full tests	pnpm run test	You want the repository-level Astro, integration, and language-tools test sequence.
Run Astro-focused tests	pnpm run test:astro	You changed the core Astro package.
Run integration tests	pnpm run test:integrations	You changed create-astro or an Astro integration package.
Run type checking	pnpm run typecheck	You changed TypeScript surfaces or shared types.
Run linting	pnpm run lint	You need static analysis before review or CI.
Run smoke tests	pnpm run test:smoke	You need a fast confidence pass for examples and docs builds.

Next Steps

If you are developing an Astro site, continue with project structure, pages, routing, and component authoring so that the dev server workflow has concrete files to serve. If you are contributing to the repository, pair this page with the CLI reference for command behavior, the integrations overview for package-specific test scope, and the container or testing references for component-level test strategies. For build failures, start from the smallest reproducing fixture, identify whether it exercises assets, routes, permissions, concurrency, or framework integration, and then expand to the broader root scripts only after the focused case passes.