Adapter and Deployment Integrations
Purpose and Scope
Astro uses integrations as the extension mechanism for adding rendering frameworks, content tools, and deployment behavior. An adapter is the deployment-specific form of integration: it connects Astro’s server rendering output to the conventions and request APIs of a hosting platform. In user-facing terms, an adapter is what lets an Astro project use on-demand rendering, commonly called SSR, on a target such as Cloudflare, Netlify, or a Node runtime. The official docs describe adapters as integrations that implement host-specific request handling and configure the build for host conventions.
This page groups the deployment adapters represented in the supplied repository evidence and explains how they fit beside other official integrations. The important distinction is that all of these packages participate in the integrations workspace, but not every integration is an adapter. Alpine is a front-end framework integration, while MDX and Markdoc are content authoring integrations. Cloudflare, Netlify, and Node are deployment adapters in this evidence set, and their build project files show extra runtime-facing inputs such as virtual type declarations and internal helper dependencies. Sources: packages/integrations/alpinejs/tsconfig.build.json, packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json
Relevant Source Files
- packages/integrations/cloudflare/tsconfig.build.json — build project for the Cloudflare adapter; it includes source files plus virtual declarations and references Astro, internal helpers, and underscore redirects.
- packages/integrations/netlify/tsconfig.build.json — build project for the Netlify adapter; it has the same visible dependency shape as Cloudflare, including virtual declarations and underscore redirects.
- packages/integrations/node/tsconfig.build.json — build project for the Node adapter; it includes adapter source and virtual declarations while depending on Astro and internal helpers.
- packages/integrations/alpinejs/tsconfig.build.json — comparison point for a non-adapter official integration that only references Astro in the supplied build config.
- packages/integrations/markdoc/tsconfig.build.json — comparison point for a content integration that depends on Astro plus internal helper, Markdown, and Prism packages.
- packages/integrations/mdx/tsconfig.build.json — comparison point for a content integration that depends on Astro plus internal helper and Markdown-related packages.
Adapter Model
The official Adapter API describes an adapter as a special integration that calls setAdapter() from the astro:config:done integration hook. That adapter declaration gives Astro a name for logging, a way to resolve the server entrypoint, a server entrypoint module, and a supported feature matrix. Those API details are product-facing documentation rather than direct code in the supplied snippets, but they explain why deployment packages live under packages/integrations: an adapter still uses the same integration lifecycle, then adds a server runtime contract that ordinary integrations do not need.
The repository evidence reinforces that distinction through build boundaries. The Cloudflare, Netlify, and Node adapter build configs all extend the shared repository TypeScript build configuration and explicitly include ./src plus ./virtual.d.ts. That pairing suggests each adapter compiles package source while also exposing or consuming generated virtual module types for its runtime integration surface. The framework and content examples do not all include the same visible virtual declaration file, which is a useful signal when identifying deployment-oriented packages in the integrations workspace. Sources: packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json
System-to-Code Mapping
| Capability | Repository signal | What it means for maintainers |
|---|---|---|
| Shared integration build baseline | All listed configs extend ../../../configs/tsconfig.build.json | Official integrations are built with the same workspace TypeScript build conventions. |
| Core Astro coupling | All listed configs reference ../../astro/tsconfig.json | Adapters and other integrations typecheck against the Astro package surface. |
| Deployment adapter packages | Cloudflare, Netlify, and Node include ./src and ./virtual.d.ts | These packages have runtime source plus virtual type surfaces in the supplied evidence. |
| Redirect support in edge-style adapters | Cloudflare and Netlify reference ../../underscore-redirects/tsconfig.json | Those adapters share an internal redirects helper package in their build graph. |
| Internal helper usage | Cloudflare, Netlify, Node, MDX, and Markdoc reference ../../internal-helpers/tsconfig.json | Several official integrations depend on shared internal utilities rather than duplicating workspace logic. |
| Non-adapter contrast | Alpine references Astro only in this snippet | Renderer-style integrations can be much thinner from the build graph perspective. |
The most concrete deployment-family split in the supplied source is the reference graph. Cloudflare and Netlify both reference Astro, internal helpers, and underscore redirects. Node references Astro and internal helpers, but not underscore redirects in this snippet. Alpine references only Astro, while MDX and Markdoc reference Markdown-related packages because their job is content processing rather than deployment. This lets maintainers reason about impact: changes to underscore redirects are more likely to affect Cloudflare and Netlify adapter builds than the Node adapter or renderer packages. Sources: packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json, packages/integrations/alpinejs/tsconfig.build.json, packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json
Package Family Reference
| Package area | Kind | Visible build inputs | Referenced workspace packages |
|---|---|---|---|
packages/integrations/cloudflare | Deployment adapter | ./src, ./virtual.d.ts | Astro, internal helpers, underscore redirects |
packages/integrations/netlify | Deployment adapter | ./src, ./virtual.d.ts | Astro, internal helpers, underscore redirects |
packages/integrations/node | Deployment adapter | ./src, ./virtual.d.ts | Astro, internal helpers |
packages/integrations/alpinejs | UI integration comparison | No explicit include in snippet | Astro |
packages/integrations/markdoc | Content integration comparison | No explicit include in snippet | Astro, internal helpers, markdown remark, Astro Prism |
packages/integrations/mdx | Content integration comparison | No explicit include in snippet | Astro, internal helpers, markdown remark, markdown satteri |
When choosing an adapter, users normally start from hosting needs rather than build graph details. Cloudflare and Netlify target platform-specific deployment environments, while Node is the general server runtime family for projects that will run behind a Node server process or compatible hosting layer. In configuration, users add the adapter as an integration, typically through the documented integration workflow such as astro add when supported, or by installing the package and adding it to the Astro config manually. The repository evidence here is not the end-user configuration file; it is the monorepo build shape that keeps those packages typechecked and publishable.
Execution Flow
A typical adapter workflow begins with an Astro project that needs server output, not just static files. The project adds a deployment adapter integration, the adapter participates in Astro’s integration hooks, and during configuration completion it declares itself to Astro with the Adapter API. Astro then builds the application with the selected output mode and emits server-facing artifacts that the adapter’s server entrypoint can handle on the target platform. The host-specific package is responsible for connecting platform request events to Astro’s server rendering entrypoint and shaping build output to match deployment conventions.
From a repository-maintenance perspective, the TypeScript project references are the first dependency checkpoint before runtime tests or hosted integration tests. A change in the core Astro package can affect every listed integration because all of them reference ../../astro/tsconfig.json. A change in shared helper code can affect Cloudflare, Netlify, Node, MDX, and Markdoc in the supplied evidence. A change in underscore redirect handling should be reviewed especially against Cloudflare and Netlify because both adapter build configs reference that helper package. Sources: packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json
Implementation Details and Next Steps
The key implementation pattern is that deployment adapters remain normal integrations at the package level while adding a server runtime role. Their build configs do not independently define the Adapter API, but they show the package boundary that makes adapter code compile against Astro and shared workspace libraries. The repeated extends value keeps adapter builds aligned with the monorepo TypeScript baseline, and the references arrays make cross-package type dependencies explicit. That explicitness matters in a large integrations workspace because it supports incremental builds and makes dependency ownership visible.
For readers implementing or changing deployment behavior, start with the adapter package that matches the target runtime, then trace from its build project references to the shared packages it depends on. For conceptual API work, read the Adapter API and Integration API docs together: the adapter is declared through integration hooks, but its purpose is request-time server rendering. For broader navigation, continue to the deployment overview for output modes, the server-side rendering and adapters page for runtime behavior, and the CLI reference for commands that add integrations or build projects.