Astro Adapter API
Astro is designed to make it easy to deploy to any cloud provider for SSR (server-side rendering). This ability is provided by adapters, which are integrations. See the SSR guide to learn how to use an existing adapter.
What is an adapterSection titled What is an adapter
An adapter is a special kind of integration that provides an entrypoint for server-side rendering. An adapter does two things:
- Implements host-specific APIs for handling requests.
- Configures the build according to host conventions.
Building an AdapterSection titled Building an Adapter
An adapter is an integration and can do anything that an integration can do.
An adapter must call the
setAdapter API in the
astro:config:done hook like so:
The object passed into
setAdapter is defined as:
The properties are:
- name: A unique name for your adapter, used for logging.
- serverEntrypoint: The entrypoint for server-side rendering.
- exports: An array of named exports when used in conjunction with
Server EntrypointSection titled Server Entrypoint
Astro’s adapter API attempts to work with any type of host, and gives a flexible way to conform to the host APIs.
ExportsSection titled Exports
Some serverless hosts expect you to export a function, such as
With the adapter API you achieve this by implementing
createExports in your
And then in your integration, where you call
setAdapter, provide this name in
StartSection titled Start
Some hosts expect you to start the server yourselves, for example by listening to a port. For these types of hosts, the adapter API allows you to export a
start function which will be called when the bundle script is run.
Section titled astro/app
This module is used for rendering pages that have been prebuilt through
astro build. Astro uses the standard Request and Response objects. Hosts that have a different API for request/response should convert to these types in their adapter.
The following methods are provided:
Section titled app.render(request)
This method calls the Astro page that matches the request, renders it, and returns a Promise to a Response object. This also works for API routes, that do not render pages.
Section titled app.match(request)
This method is used to determine if a request is matched by the Astro app’s routing rules.
You can usually call
app.render(request) without using
.match because Astro handles 404s if you provide a
404.astro file. Use
app.match(request) if you want to handle 404s in a different way.
Allow installation via Section titled Allow installation via astro add
astro add command allows users to easily add integrations and adapters to their project. If you want your adapter to be installable with this tool, add
astro-adapter to the
keywords field in your
Once you publish your adapter to npm, running
astro add example will install your package with any peer dependencies specified in your
package.json. We will also instruct users to update their project config manually.