Skip to content

fix(container-reference): add/update API reference blocks #12511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 7, 2025
Merged

fix(container-reference): add/update API reference blocks #12511

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
90de6b8
fix(container-reference): add/update API reference blocks
ArmandPhilippot Oct 6, 2025
cb22795
Merge branch 'main' into fix/container-api-references
ArmandPhilippot Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 53 additions & 11 deletions src/content/docs/en/reference/container-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,11 @@ This API is experimental and subject to breaking changes, even in [minor or patc

## `create()`

<p>

**Type:** `(options?: AstroContainerOptions) => Promise<experimental_AstroContainer>`
</p>

Creates a new instance of the container.

```js
Expand Down Expand Up @@ -50,13 +55,21 @@ export type AddServerRenderer =

### `streaming` option

**Type:** `boolean`
<p>

**Type:** `boolean`<br />
**Default:** `false`
</p>

Enables rendering components using [HTML streaming](/en/guides/on-demand-rendering/#html-streaming).

### `renderers` option

**Type:** `AddServerRenderer[]`
<p>

**Type:** `AddServerRenderer[]`<br />
**Default:** `[]`
</p>

A list of loaded client renderers required by the component. Use this if your `.astro` component renders any [UI framework components](/en/guides/framework-components/) or MDX using an official Astro integration (e.g. React, Vue, etc.).

Expand Down Expand Up @@ -106,15 +119,20 @@ import vueRenderer from "@astrojs/vue/server.js";
import mdxRenderer from "@astrojs/mdx/server.js";

const container = await experimental_AstroContainer.create();
container.addServerRenderer({renderer: vueRenderer});
container.addServerRenderer({renderer: mdxRenderer});
container.addServerRenderer({ renderer: vueRenderer });
container.addServerRenderer({ renderer: mdxRenderer });

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

## `renderToString()`

<p>

**Type:** <code>(component: AstroComponentFactory; options?: <a href="#rendering-options">ContainerRenderOptions</a>) => Promise&lt;string&gt;</code>
</p>

This function renders a specified component inside a container. It takes an Astro component as an argument and it returns a string that represents the HTML/content rendered by the Astro component.

```js
Expand All @@ -131,6 +149,11 @@ It also accepts an object as a second argument that can contain a [number of opt

## `renderToResponse()`

<p>

**Type:** <code>(component: AstroComponentFactory; options?: <a href="#rendering-options">ContainerRenderOptions</a>) => Promise&lt;Response&gt;</code>
</p>

It renders a component, and it returns a `Response` object.

```js
Expand All @@ -154,15 +177,19 @@ export type ContainerRenderOptions = {
request?: Request;
params?: Record<string, string | undefined>;
locals?: App.Locals;
routeType?: "page" | "endpoint";
routeType?: RouteType;
partial?: boolean;
};
```

These optional values can be passed to the rendering function in order to provide additional information necessary for an Astro component to properly render.

### `slots`

**Type:** `Record<string, any>`
<p>

**Type**: `Record<string, any>`
</p>

An option to pass content to be rendered with [`<slots>`](/en/basics/astro-components/#slots).

Expand Down Expand Up @@ -224,7 +251,10 @@ const result = await container.renderToString(Card, {

### `props` option

**Type:** `Record<string, unknown>`
<p>

**Type**: `Record<string, unknown>`
</p>

An option to pass [properties](/en/basics/astro-components/#component-props) for Astro components.

Expand Down Expand Up @@ -252,7 +282,10 @@ const { name } = Astro.props;

### `request` option

**Type:** `Request`
<p>

**Type**: `Request`
</p>

An option to pass a `Request` with information about the path/URL the component will render.

Expand All @@ -274,7 +307,10 @@ const result = await container.renderToString(Card, {

### `params` option

**Type:** `Record<string, string | undefined>`
<p>

**Type**: `Record<string, string | undefined>`
</p>

An object to pass information about the path parameter to an Astro component responsible for [generating dynamic routes](/en/guides/routing/#dynamic-routes).

Expand All @@ -300,7 +336,10 @@ const result = await container.renderToString(LocaleSlug, {

### `locals` options

**Type:** `App.Locals`
<p>

**Type**: `App.Locals`
</p>

An option to pass information from [`Astro.locals`](/en/reference/api-reference/#locals) for rendering your component.

Expand Down Expand Up @@ -341,7 +380,10 @@ test("User is out", async () => {

### `routeType` option

**Type:** `"page" | "endpoint"`
<p>

**Type**: `RouteType`
</p>

An option available when using `renderToResponse()` to specify that you are rendering an [endpoint](/en/guides/endpoints/):

Expand Down