The Integration System provides Astro with a flexible and extensible architecture, allowing integrations to enhance and customize the framework’s behavior throughout the build and development lifecycle. Central to this system is the AstroIntegration API, a standardized hook-based interface used by integrations to inject routes, modify configuration, extend Vite build pipelines, and integrate third-party frameworks and services.
Astro's integrations span multiple categories, including UI framework renderers, content processors, deployment adapters, and other plugins that enrich project capabilities. Each integration registers lifecycle hooks that correspond to specific phases of Astro’s internal processes, such as configuration setup, server start, and build stages.
For focused coverage on specific integration types, see the corresponding child pages:
Astro integrations are JavaScript objects adhering to the AstroIntegration interface, which primarily includes a name and a hooks object mapping lifecycle events to implementations.
During the lifecycle of an Astro project, integrations are instantiated and their hooks invoked at designated points, allowing them to perform actions such as updating the Astro configuration, adding custom routes or scripts, registering UI framework renderers, and injecting or modifying Vite plugins.
Title: Integration Hook Lifecycle Diagram
Sources: packages/astro/src/types/public/integrations.ts1-150 packages/integrations/vercel/package.json1-61 packages/integrations/netlify/package.json1-67 packages/integrations/svelte/package.json1-64
Astro exposes multiple well-defined hooks that integrations can implement. Each hook receives a context object with utilities and state relevant to that phase.
| Hook Name | Lifecycle Phase | Common Uses and Capabilities |
|---|---|---|
astro:config:setup | Configuration | Update config, add routes/scripts, register renderers, add Vite plugins, watch files |
astro:config:done | Configuration | Access final resolved config and logger |
astro:server:setup | Development | Add development server middlewares |
astro:server:start | Development | Access started dev server instance |
astro:build:start | Build | Initialize build resources |
astro:build:setup | Build | Update build-specific config |
astro:build:ssr | Build | Modify SSR manifest and entry points |
astro:build:done | Build | Post-build artifact manipulation |
Title: Hook Execution Sequence
Sources: packages/astro/src/integrations/hooks.ts1-100 packages/integrations/vercel/CHANGELOG.md37-54 packages/integrations/node/CHANGELOG.md115-118
Hooks receive context objects with methods and data enabling them to modify behavior.
astro:config:setup Example Context HighlightsupdateConfig: Merges partial updates into the Astro config. Used by adapters to set options like staticHeaders.injectRoute: Add programmatically generated pages or endpoints.injectScript: Inject scripts globally or at specific injection points.addRenderer: Register UI framework renderers (e.g., React, Vue).addWatchFile: Monitor additional files in dev mode. For example, the Cloudflare adapter might watch wrangler.json packages/integrations/cloudflare/CHANGELOG.md48-49astro:build:done Context Use Cases_redirects files packages/integrations/netlify/package.json44).@vercel/nft packages/integrations/vercel/package.json44Sources: packages/integrations/vercel/CHANGELOG.md37-54 packages/integrations/cloudflare/CHANGELOG.md67-72
Official Astro integrations export a factory function returning the integration object with hooks. This pattern enables configuration options and reusability.
Title: Integration Factory Pattern
Official integration packages use consistent package.json patterns for discovery:
| Field | Pattern / Content | Purpose |
|---|---|---|
keywords | Include "astro-integration", "astro-adapter", or "renderer" | Classified as Astro integration packages |
exports["."] | Points to main integration factory entry | Entry point for setup |
exports["./server.js"] | Server-side component rendering | SSR runtime for the integration |
peerDependencies | astro version requirement (e.g. ^7.0.0) | Version compatibility |
Sources: packages/integrations/vercel/package.json13-28 packages/integrations/svelte/package.json13-29 packages/integrations/mdx/package.json13-25
Adapters configure Astro projects for specific deployment environments including Vercel, Cloudflare Workers, Netlify, and Node.js servers. They manage build-time transformations, serverless function bundling, and platform-specific capabilities like image services.
For details, see Deployment Adapters.
Enable usage of frameworks such as React, Vue, Svelte, Solid, and Preact within Astro projects. These integrations supply client and server entrypoints, coordinate hydration directives (like client:load), and integrate associated Vite plugins.
For details, see UI Framework Integrations.
Provide advanced support for content formats like MDX, Markdoc, and markdown-remark. They enable rich content transformation pipelines and embed components inside markdown.
For details, see Content Processing Integrations.
Provides a SQLite-backed integration supporting database schema definition, migration queries, and CLI commands.
For details, see Astro DB Integration.
Official Astro integrations share a common build infrastructure built around astro-scripts.
Title: Build Infrastructure
Sources: packages/integrations/vercel/package.json33-41 packages/integrations/node/package.json28-35 packages/integrations/svelte/package.json34-40
Title: Code Entity Mapping - Lifecycle Hooks
Sources: packages/astro/src/types/public/integrations.ts1-150 packages/astro/src/integrations/hooks.ts1-100
Title: Code Entity Mapping - Vercel Adapter
Sources: packages/integrations/vercel/package.json19-28 packages/integrations/vercel/package.json44
Please refer to the following paths and line ranges for implementation details:
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.