> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
import { experimental_AstroContainer as AstroContainer } from 'astro/container';
```

## AstroContainer.create

Create a new container instance.

```typescript theme={null}
AstroContainer.create(options?: AstroContainerOptions): Promise<AstroContainer>
```

<ParamField path="options" type="AstroContainerOptions">
  Container configuration options.

  <ParamField path="streaming" type="boolean">
    Enable streaming during rendering.

    **Default:** `false`

    ```typescript theme={null}
    const container = await AstroContainer.create({
      streaming: true,
    });
    ```
  </ParamField>

  <ParamField path="renderers" type="SSRLoadedRenderer[]">
    Array of renderers for UI framework components (React, Vue, etc.).

    **Default:** `[]`

    ```typescript theme={null}
    import reactRenderer from '@astrojs/react/server.js';
    import vueRenderer from '@astrojs/vue/server.js';

    const container = await AstroContainer.create({
      renderers: [reactRenderer, vueRenderer],
    });
    ```
  </ParamField>

  <ParamField path="astroConfig" type="AstroContainerUserConfig">
    Subset of Astro configuration options.

    ```typescript theme={null}
    const container = await AstroContainer.create({
      astroConfig: {
        trailingSlash: 'never',
        site: 'https://example.com',
      },
    });
    ```
  </ParamField>
</ParamField>

### Example

```typescript theme={null}
import { experimental_AstroContainer as AstroContainer } from 'astro/container';

const container = await AstroContainer.create();
```

## renderToString

Render a component to an HTML string.

```typescript theme={null}
container.renderToString(
  component: AstroComponentFactory,
  options?: ContainerRenderOptions
): Promise<string>
```

<ParamField path="component" type="AstroComponentFactory" required>
  The Astro component to render.
</ParamField>

<ParamField path="options" type="ContainerRenderOptions">
  Rendering options.

  <ParamField path="request" type="Request">
    Request object for the render. Used to populate `Astro.request` and `Astro.url`.

    ```typescript theme={null}
    const html = await container.renderToString(Component, {
      request: new Request('https://example.com/page'),
    });
    ```
  </ParamField>

  <ParamField path="params" type="Record<string, string | undefined>">
    Route parameters for dynamic routes.

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

  <ParamField path="props" type="Record<string, any>">
    Props to pass to the component via `Astro.props`.

    ```typescript theme={null}
    const html = await container.renderToString(Component, {
      props: { title: 'Hello', count: 42 },
    });
    ```
  </ParamField>

  <ParamField path="slots" type="Record<string, any>">
    Slot content to pass to the component.

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

  <ParamField path="locals" type="App.Locals">
    Locals object accessible via `Astro.locals`.

    ```typescript theme={null}
    const html = await container.renderToString(Component, {
      locals: { user: { id: '123', name: 'John' } },
    });
    ```
  </ParamField>

  <ParamField path="routeType" type="'page' | 'endpoint'">
    Type of route being rendered.

    **Default:** `'page'`

    ```typescript theme={null}
    const html = await container.renderToString(Endpoint, {
      routeType: 'endpoint',
    });
    ```
  </ParamField>

  <ParamField path="partial" type="boolean">
    When `false`, renders the component as a full page. When `true`, renders as a partial.

    **Default:** `true`

    ```typescript theme={null}
    const html = await container.renderToString(Component, {
      partial: false, // Render complete page
    });
    ```
  </ParamField>
</ParamField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
container.renderToResponse(
  component: AstroComponentFactory,
  options?: ContainerRenderOptions
): Promise<Response>
```

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

### Example

```typescript theme={null}
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.

```typescript theme={null}
container.addServerRenderer(options: AddServerRenderer): void
```

<ParamField path="options" type="AddServerRenderer" required>
  Renderer options.

  <ParamField path="renderer" type="NamedSSRLoadedRendererValue | SSRLoadedRendererValue" required>
    The server renderer exported by an integration.
  </ParamField>

  <ParamField path="name" type="string">
    Name of the renderer. Required if the renderer is not a named renderer.
  </ParamField>
</ParamField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
container.addClientRenderer(options: AddClientRenderer): void
```

<ParamField path="options" type="AddClientRenderer" required>
  Client renderer options.

  <ParamField path="name" type="string" required>
    Name of the renderer. Must match the server renderer name.
  </ParamField>

  <ParamField path="entrypoint" type="string" required>
    Client-side entrypoint for the renderer.
  </ParamField>
</ParamField>

### Example

```typescript theme={null}
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()`.

```typescript theme={null}
container.insertPageRoute(
  route: string,
  component: AstroComponentFactory,
  params?: Record<string, string | undefined>
): void
```

<ParamField path="route" type="string" required>
  The URL path that will render the component.
</ParamField>

<ParamField path="component" type="AstroComponentFactory" required>
  The component to render for this route.
</ParamField>

<ParamField path="params" type="Record<string, string | undefined>">
  Route parameters for dynamic routes.
</ParamField>

### Example

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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' },
});
```