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.

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.

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:

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js'
        });
      },
    },
  };
}

The object passed into setAdapter is defined as:

interface AstroAdapter {
  name: string;
  serverEntrypoint?: string;
  exports?: string[];
}

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 createExports (explained below).

Astro’s adapter API attempts to work with any type of host, and gives a flexible way to conform to the host APIs.

Some serverless hosts expect you to export a function, such as handler:

export function handler(event, context) {
}

With the adapter API you achieve this by implementing createExports in your serverEntrypoint:

import { App } from 'astro/app';

export function createExports(manifest) {
  const app = new App(manifest);

  const handler = (event, context) => {
    // ...
  };

  return { handler };
}

And then in your integration, where you call setAdapter, provide this name in exports:

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          exports: ['handler'],
        });
      },
    },
  };
}

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.

import { App } from 'astro/app';

export function start(manifest) {
  const app = new App(manifest);

  addEventListener('fetch', event => {
    // ...
  });
}

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.

import { App } from 'astro/app';
import http from 'http';

export function start(manifest) {
  const app = new App(manifest);

  addEventListener('fetch', event => {
    event.respondWith(
      app.render(event.request)
    );
  });
}

The following methods are provided:

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.

const response = await app.render(request);

The method accepts a mandatory request argument, and two other optional arguments: routeData and locals.

Provide a value for routeData if you already know the route to render. Doing so will bypass the internal call to app.match to determine the route to render.

When used, locals must be the third argument passed. You can pass undefined for routeData if you are not targeting a specific route.

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.

const privateHeader = request.headers.get("x-private-header");
let locals = {};
try {
    if (privateHeader) {
        locals = JSON.parse(privateHeader);
    }
} finally {
    const response = await app.render(request, undefined, locals);
}

This method is used to determine if a request is matched by the Astro app’s routing rules.

if(app.match(request)) {
  const response = await app.render(request);
}

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.

The 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 package.json:

{
  "name": "example",
  "keywords": ["astro-adapter"],
}

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.