Container API

API reference for the Astro Container API - server-side component rendering

The Container API allows you to render Astro components in isolation, useful for testing, server-side rendering, and on-demand page generation.

Importing

import { experimental_AstroContainer as AstroContainer } from 'astro/container';

AstroContainer.create

Create a new container instance.

AstroContainer.create(options?: AstroContainerOptions): Promise<AstroContainer>

options · AstroContainerOptions

Container configuration options.

streaming · boolean

Enable streaming during rendering.

Default: false

const container = await AstroContainer.create({
  streaming: true,
});

renderers · SSRLoadedRenderer[]

Array of renderers for UI framework components (React, Vue, etc.).

Default: []

import reactRenderer from '@astrojs/react/server.js';
import vueRenderer from '@astrojs/vue/server.js';

const container = await AstroContainer.create({
  renderers: [reactRenderer, vueRenderer],
});

astroConfig · AstroContainerUserConfig

Subset of Astro configuration options.

const container = await AstroContainer.create({
  astroConfig: {
    trailingSlash: 'never',
    site: 'https://example.com',
  },
});

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';

const container = await AstroContainer.create();

renderToString

Render a component to an HTML string.

container.renderToString(
  component: AstroComponentFactory,
  options?: ContainerRenderOptions
): Promise<string>

component · AstroComponentFactory · required

The Astro component to render.

options · ContainerRenderOptions

Rendering options.

request · Request

Request object for the render. Used to populate Astro.request and Astro.url.

const html = await container.renderToString(Component, {
  request: new Request('https://example.com/page'),
});

params · Record<string, string | undefined>

Route parameters for dynamic routes.

// For src/pages/blog/[slug].astro
const html = await container.renderToString(Component, {
  params: { slug: 'my-post' },
});

props · Record<string, any>

Props to pass to the component via Astro.props.

const html = await container.renderToString(Component, {
  props: { title: 'Hello', count: 42 },
});

slots · Record<string, any>

Slot content to pass to the component.

const html = await container.renderToString(Component, {
  slots: {
    default: 'Main content',
    header: '<h1>Header</h1>',
  },
});

locals · App.Locals

Locals object accessible via Astro.locals.

const html = await container.renderToString(Component, {
  locals: { user: { id: '123', name: 'John' } },
});

routeType · 'page' | 'endpoint'

Type of route being rendered.

Default: 'page'

const html = await container.renderToString(Endpoint, {
  routeType: 'endpoint',
});

partial · boolean

When false, renders the component as a full page. When true, renders as a partial.

Default: true

const html = await container.renderToString(Component, {
  partial: false, // Render complete page
});

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import Card from '../src/components/Card.astro';

const container = await AstroContainer.create();

const html = await container.renderToString(Card, {
  props: {
    title: 'My Card',
    description: 'Card description',
  },
});

console.log(html); // <div class="card">...</div>

renderToResponse

Render a component and return a Response object.

container.renderToResponse(
  component: AstroComponentFactory,
  options?: ContainerRenderOptions
): Promise<Response>

Accepts the same parameters as renderToString, but returns a Response object instead of a string.

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import Page from '../src/pages/index.astro';

const container = await AstroContainer.create();

const response = await container.renderToResponse(Page, {
  request: new Request('https://example.com/'),
});

console.log(response.status); // 200
const html = await response.text();

addServerRenderer

Manually add a server renderer to the container.

container.addServerRenderer(options: AddServerRenderer): void

options · AddServerRenderer · required

Renderer options.

renderer · NamedSSRLoadedRendererValue | SSRLoadedRendererValue · required

The server renderer exported by an integration.

name · string

Name of the renderer. Required if the renderer is not a named renderer.

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import reactRenderer from '@astrojs/react/server.js';
import vueRenderer from '@astrojs/vue/server.js';

const container = await AstroContainer.create();

// Named renderer (has .name property)
container.addServerRenderer({ renderer: reactRenderer });

// Non-named renderer
container.addServerRenderer({ 
  renderer: vueRenderer, 
  name: '@astrojs/vue' 
});

addClientRenderer

Manually add a client renderer to the container for components using client:* directives.

container.addClientRenderer(options: AddClientRenderer): void

options · AddClientRenderer · required

Client renderer options.

name · string · required

Name of the renderer. Must match the server renderer name.

entrypoint · string · required

Client-side entrypoint for the renderer.

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import reactRenderer from '@astrojs/react/server.js';

const container = await AstroContainer.create();

// Add server renderer first
container.addServerRenderer({ renderer: reactRenderer });

// Then add client renderer
container.addClientRenderer({
  name: '@astrojs/react',
  entrypoint: '@astrojs/react/client.js',
});

insertPageRoute

Register a page route in the container for use with Astro.rewrite().

container.insertPageRoute(
  route: string,
  component: AstroComponentFactory,
  params?: Record<string, string | undefined>
): void

route · string · required

The URL path that will render the component.

component · AstroComponentFactory · required

The component to render for this route.

params · Record<string, string | undefined>

Route parameters for dynamic routes.

Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import Home from '../src/pages/index.astro';
import About from '../src/pages/about.astro';
import Blog from '../src/pages/blog/[slug].astro';

const container = await AstroContainer.create();

container.insertPageRoute('/', Home);
container.insertPageRoute('/about', About);
container.insertPageRoute('/blog/[slug]', Blog, { slug: 'my-post' });

// Now these routes can be used with Astro.rewrite()

Testing Example

The Container API is particularly useful for testing:

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import { expect, test } from 'vitest';
import Card from '../src/components/Card.astro';

test('Card component renders correctly', async () => {
  const container = await AstroContainer.create();
  
  const html = await container.renderToString(Card, {
    props: {
      title: 'Test Card',
      description: 'This is a test',
    },
  });
  
  expect(html).toContain('Test Card');
  expect(html).toContain('This is a test');
});

test('Card with slots', async () => {
  const container = await AstroContainer.create();
  
  const html = await container.renderToString(Card, {
    slots: {
      default: '<p>Slot content</p>',
    },
  });
  
  expect(html).toContain('Slot content');
});

Framework Component Example

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import reactRenderer from '@astrojs/react/server.js';
import MyReactComponent from '../src/components/MyReactComponent.astro';

const container = await AstroContainer.create();

// Add React renderer
container.addServerRenderer({ renderer: reactRenderer });
container.addClientRenderer({
  name: '@astrojs/react',
  entrypoint: '@astrojs/react/client.js',
});

// Render component with React
const html = await container.renderToString(MyReactComponent, {
  props: { message: 'Hello from React' },
});