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
- adapterFeatures: An object that enables specific features that must be supported by the adapter. These features will change the built output, and the adapter must implement the proper logic to handle the different output.
- supportedAstroFeatures: A map of Astro built-in features. This allows Astro to determine which features an adapter is unable or unwilling to support so appropriate error messages can be provided.
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: Request, options?: RenderOptions)
app.render(request: Request, options?: RenderOptions)
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 RenderOptions
Section titled addCookieHeader
Whether or not to automatically add all cookies written by
Astro.cookie.set() to the response headers.
When set to
true, they will be added to the
Set-Cookie header of the response as comma separated key-value pairs. You can use the standard
response.headers.getSetCookie() API to read them individually.
When set to
false(default), the cookies will only be available from
Section titled clientAddress
The client IP address that will be made available as
Astro.clientAddress in pages, and as
ctx.clientAddress in API routes and middleware.
The example below reads the
x-forwarded-for header and passes it as
clientAddress. This value becomes available to the user as
Section titled locals
context.locals object used to store and access information during the lifecycle of a request.
The example below reads a header named
x-private-header, attempts to parse it as an object and pass it to
locals, which can then be passed to any middleware function.
Section titled routeData
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.
Astro featuresSection titled Astro features
Astro features are a way for an adapter to tell Astro whether they are able to support a feature, and also the adapter’s level of support.
When using these properties, Astro will:
- run specific validation;
- emit contextual to the logs;
These operations are run based on the features supported or not supported, their level of support, and the configuration that the user uses.
The following configuration tells Astro that this adapter has experimental support for assets, but the adapter is not compatible with the built-in services Sharp and Squoosh:
Astro will log a warning to the terminal:
and an error if the service used for assets is not compatible with the adapter:
Adapter featuresSection titled Adapter features
A set of features that changes the output of the emitted files. When an adapter opts in to these features, they will get additional information inside specific hooks.
Section titled functionPerRoute
This is a feature that is enabled when using SSR only. By default, Astro emits a single
entry.mjs file, which is responsible for emitting the rendered page on each request.
true, Astro will instead create a separate file for each route defined in the project.
Each file emitted will only render one page. The pages will be emitted inside a
dist/pages/ directory (or under a
/pages/ directory in the directory specified for
outDir), and the emitted files will keep the same file paths of the
The files inside the
pages/ directory of the build will mirror the directory structure of your page files in
src/pages/, for example:
Enable the feature by passing
true to the adapter.
Then, consume the hook
astro:build:ssr, which will give you an
entryPoints object that maps a page route to the physical file emitted after the build.
entryFile is of type
URL and represents the physical path of the file in the file system. This means that the paths change based on the OS where the code runs.
Serverless environmentsSection titled Serverless environments
Each of these routes is subject to a cold start when the handler runs, which may cause some delay. This delay is influenced by different factors.
functionPerRoute: false, there is only one single handler in charge of rendering all your routes. When this handler is first triggered, you will be subject to a cold start. Then, all other routes should function without delay. However, you will lose the benefit of code splitting that
functionPerRoute: true provides.
It’s important that you understand your hosting platform, and how it works, in order to choose the appropriate
functionPerRoute configuration for your project.
Section titled edgeMiddleware
Defines whether any SSR middleware code will be bundled when built.
When enabled, this prevents middleware code from being bundled and imported by all pages during the build:
Then, consume the hook
astro:build:ssr, which will give you a
URL to the physical file on the file system.