astro

The core framework. Every other package in the repo either depends on astro or extends it via the integration API.

Purpose

astro ships:

• The astro CLI (bin/astro.mjs → src/cli/).
• The framework runtime: dev server, build pipeline, routing, content collections, assets, server islands, sessions, middleware, i18n, view transitions, dev toolbar, actions, env, CSP.
• The Vite plugin stack that compiles .astro files, generates routes, and powers the dev experience.
• The integration interface that adapters and framework integrations target.
• The programmatic JS API: dev, build, preview, sync from the package root; App and the manifest from astro/app/*; programmatic component rendering from astro/container.

Directory layout

packages/astro/
├── bin/                # CLI shim
├── components/         # Built-in .astro components (Code, Debug, Image, Picture, Font, ViewTransitions)
├── e2e/                # Playwright e2e tests
├── performance/        # Performance harness scripts
├── src/
│   ├── actions/        # astro:actions virtual module + Vite plugin
│   ├── assets/         # astro:assets, image service, font subsystem, SVG optimizer
│   ├── cli/            # `astro` CLI commands
│   ├── config/         # User config helpers (defineConfig, defineLiveCollection, etc.)
│   ├── container/      # Programmatic component renderer
│   ├── content/        # Content collections, content layer, loaders
│   ├── core/           # Node-only framework code (build, dev, routing, render)
│   ├── csp/            # (under core/) Content Security Policy
│   ├── env/            # astro:env typed environment variables
│   ├── events/         # Telemetry events
│   ├── i18n/           # Internationalization router and middleware
│   ├── integrations/   # Integration loader + types
│   ├── jsx/, jsx-runtime/  # The Astro JSX runtime
│   ├── manifest/       # Build-time manifest helpers
│   ├── preferences/    # User-preferences store (astro pref)
│   ├── prefetch/       # Built-in prefetch helper
│   ├── prerender/      # Per-route prerender configuration
│   ├── runtime/        # client/, server/, compiler/, prerender/ — non-Node code
│   ├── template/       # Internal HTML templates (e.g. error overlay shell)
│   ├── toolbar/        # Dev toolbar plugin host
│   ├── transitions/    # View transitions
│   ├── types/          # Public + internal types
│   ├── virtual-modules/    # astro:* virtual module entrypoints
│   └── vite-plugin-*/  # ~20 Vite plugins (see overview/architecture)
├── templates/          # Templates for `astro add`/`astro create-key`
├── test/               # mocha tests + units + fixtures
├── types/              # Hand-written .d.ts for env, jsx, etc.
└── package.json        # Hand-edited dual exports map

Entry points

The exports map in packages/astro/package.json is one of the most carefully maintained files in the repo. Major public entrypoints:

Subpath	What it is
astro	dev, build, preview, sync JS API. Source: src/index.ts → src/core/index.ts.
astro/app, astro/app/node, astro/app/manifest, astro/app/entrypoint	Production runtime used by adapters.
astro/container	Programmatic component rendering.
astro/middleware	defineMiddleware, sequence helpers.
astro/loaders	Content layer loader API.
astro/content/runtime, astro/content/runtime-assets, astro/content/config	Content collection runtime helpers.
astro/assets, astro/assets/utils, astro/assets/services/sharp, astro/assets/services/noop	Image service.
astro/jsx-runtime, astro/jsx-dev-runtime	JSX runtime that the compiler targets.
astro/zod	Bundled Zod (v4) re-export.
astro/errors	AstroUserError for integration authors.
astro/components, astro/components/Debug.astro	Built-in components.
astro/runtime/{idle,load,media,only,visible}	Hydration shims shipped to browsers.
astro/toolbar	Dev toolbar plugin authoring API.
astro/logger, astro/logger/node, astro/logger/json, astro/logger/console, astro/logger/compose	Logger entrypoints.
astro/cache/memory	In-memory cache provider implementation.

Internal-only subpaths under astro/_internal/* (used by sibling packages, never published):

• astro/_internal/assets
• astro/_internal/logger
• astro/_internal/test/test-adapter
• astro/_internal/test/test-utils
• astro/_internal/test/units/test-utils

Build script

The build is custom, not just tsc:

"prebuild": "astro-scripts prebuild --to-string \"src/runtime/server/astro-island.ts\" \"src/runtime/client/{idle,load,media,only,visible}.ts\"",
"build":    "pnpm run prebuild && astro-scripts build \"src/**/*.{ts,js}\" --copy-wasm && tsc && astro-check -- -- --root ./components",
"build:ci": "pnpm run prebuild && astro-scripts build \"src/**/*.{ts,js}\" --copy-wasm",
"dev":      "astro-scripts dev --copy-wasm --prebuild ... \"src/**/*.{ts,js}\""

The prebuild step inlines the client hydration shims as JavaScript strings, so the runtime can serve them without an extra HTTP fetch. --copy-wasm ships the @astrojs/compiler WASM next to the bundled output. astro-check then validates that the bundled components/ files type-check against the public astro API surface.

Tests

packages/astro/test/ contains thousands of test files spread across:

• Top-level *.test.js (mocha) for end-to-end framework behavior.
• units/ for pure Node node:test cases.
• fixtures/ for the test apps that loadFixture() boots.
• e2e/ (Playwright) for HMR, hydration, and client-side behavior.

See how-to-contribute / testing for the runner details.

Read next

The framework is too large for a single page. Subsystem pages live under systems:

• systems / CLI
• systems / dev server
• systems / build pipeline
• systems / routing
• systems / render context
• systems / Vite plugins
• systems / error handling

For features delivered through the framework (content collections, server islands, view transitions, …), see features.