Skip to content

Add docs for the Renderer API #13715

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

Draft
ArmandPhilippot wants to merge 3 commits into
base: main
Choose a base branch
from
+343 −190
Draft

Add docs for the Renderer API #13715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cb8b89c
Add docs for the Renderer API
ArmandPhilippot Apr 10, 2026
94ce1f2
fix link
ArmandPhilippot Apr 10, 2026
07d9ea1
add new link
ArmandPhilippot Apr 10, 2026
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
1 change: 1 addition & 0 deletions astro.sidebar.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ export const sidebar = [
items: [
'reference/integrations-reference',
'reference/adapter-reference',
'reference/renderer-reference',
'reference/content-loader-reference',
'reference/image-service-reference',
'reference/dev-toolbar-app-reference',
Expand Down
3 changes: 1 addition & 2 deletions public/_redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,7 @@

# Very old docs site redirects
# Once upon a time these URLs existed, so we try to keep them meaning something.
/reference/renderer-reference /en/reference/integrations-reference/
/en/reference/renderer-reference /en/reference/integrations-reference/
/reference/renderer-reference /en/reference/renderer-reference/
/en/core-concepts/component-hydration /en/concepts/islands/
/core-concepts/component-hydration /en/concepts/islands/
/core-concepts/collections /en/guides/content-collections/
Expand Down
191 changes: 3 additions & 188 deletions src/content/docs/en/reference/integrations-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,11 +194,11 @@ export default {

<p>

**Type:** <code>(renderer: <a href="#astrorenderer">AstroRenderer</a>) => void;</code><br />
**Type:** <code>(renderer: <a href="/en/reference/renderer-reference/#astrorenderer">AstroRenderer</a>) => void;</code><br />
**Examples:** [`svelte`](https://github.com/withastro/astro/blob/main/packages/integrations/svelte/src/index.ts), [`react`](https://github.com/withastro/astro/blob/main/packages/integrations/react/src/index.ts), [`preact`](https://github.com/withastro/astro/blob/main/packages/integrations/preact/src/index.ts), [`vue`](https://github.com/withastro/astro/blob/main/packages/integrations/vue/src/index.ts), [`solid`](https://github.com/withastro/astro/blob/main/packages/integrations/solid/src/index.ts)
</p>

A callback function to add a component framework renderer (i.e. React, Vue, Svelte, etc). You can browse the examples and type definition above for more advanced options, but here are the 2 main options to be aware of:
A callback function to [add a component framework renderer](/en/reference/renderer-reference/) (i.e. React, Vue, Svelte, etc). You can browse the examples and type definition above for more advanced options, but here are the 2 main options to be aware of:

- `clientEntrypoint` - path to a file that executes on the client whenever your component is used. This is mainly for rendering or hydrating your component with JS.
- `serverEntrypoint` - path to a file that executes during server-side requests or static builds whenever your component is used. These should render components to static markup, with hooks for hydration where applicable. [React's `renderToString` callback](https://react.dev/reference/react-dom/server/renderToString) is a classic example.
Expand Down Expand Up @@ -1438,7 +1438,6 @@ import type {
AstroIntegrationMiddleware,
AstroMiddlewareInstance,
AstroPrerenderer,
AstroRenderer,
ClientDirectiveConfig,
HookParameters,
IntegrationResolvedRoute,
Expand All @@ -1447,8 +1446,6 @@ import type {
RoutePart,
RouteType,
SSRComponentMetadata,
SSRLoadedRenderer,
SSRLoadedRendererValue,
SSRManifest,
ValidRedirectStatus,
} from "astro";
Expand Down Expand Up @@ -1608,42 +1605,6 @@ Defines an optional method describing how to render a page. This will be called

Defines an optional method called once all pages are pre-rendered. This is useful for performing cleanup tasks such as stopping a preview server.

### `AstroRenderer`

<p>

**Type:** `{ name: string; clientEntrypoint?: string | URL; serverEntrypoint: string | URL; }`
</p>

Describes a [component framework renderer added by an integration](#addrenderer-option).

#### `AstroRenderer.name`

<p>

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

The name of the component framework renderer.

#### `AstroRenderer.clientEntrypoint`

<p>

**Type:** `string | URL`
</p>

Defines the import path of the renderer that runs on the client whenever your component is used.

#### `AstroRenderer.serverEntrypoint`

<p>

**Type:** `string | URL`
</p>

Defines the import path of the renderer that runs during server-side requests or static builds whenever your component is used.

### `ClientDirectiveConfig`

<p>
Expand Down Expand Up @@ -2028,152 +1989,6 @@ A description of how to render head content from this component, including wheth

Determines whether the component contains the head content.

### `SSRLoadedRenderer`

<p>

**Type:** `{ name: string; clientEntrypoint?: string | URL; ssr: SSRLoadedRendererValue; }`
</p>

Describes a renderer available for the server to use. This is a subset of [`AstroRenderer`](#astrorenderer) with additional properties.

#### `SSRLoadedRenderer.ssr`

<p>

**Type:** [`SSRLoadedRendererValue`](#ssrloadedrenderervalue)
</p>

Defines the functions and configuration used by the server for this framework.

### `SSRLoadedRendererValue`

Contains the functions and configuration necessary to render components on the server from a specific UI framework.

#### `SSRLoadedRendererValue.name`

<p>

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

Specifies the name identifier for the renderer.

#### `SSRLoadedRendererValue.check()`

<p>

**Type:** `(Component: any, props: Record<string, any>, children: Record<string, string>, metadata?: AstroComponentMetadata) => Promise<boolean>`
</p>

Determines whether the renderer should handle the component. Called for each registered renderer until one returns `true`.

The function receives the component constructor or function, its props, slot content, and an optional [`metadata`](#astrocomponentmetadata) object containing information about the component's hydration directive and source.

#### `SSRLoadedRendererValue.renderToStaticMarkup()`

<p>

**Type:** `(Component: any, props: Record<string, any>, children: Record<string, string>, metadata?: AstroComponentMetadata) => Promise<{ html: string; attrs?: Record<string, string>; }>`
</p>

Renders a framework component to static HTML markup on the server.

The function receives the component constructor or function, its props, slot content, and an optional [`metadata`](#astrocomponentmetadata) object. Renderers can use `metadata` to determine whether the component will be hydrated on the client, which can be useful for conditionally including client-side hydration state.

#### `SSRLoadedRendererValue.supportsAstroStaticSlot`

<p>

**Type:** `boolean`<br />
<Since v="2.5.0" />
</p>

Indicates whether the renderer supports Astro's static slot optimization. When true, Astro prevents the removal of nested slots within islands.

#### `SSRLoadedRendererValue.renderHydrationScript()`

<p>

**Type:** `() => string`<br />
<Since v="4.1.0" />
</p>

Returns a framework-specific hydration script that must be injected into the HTML before the first component that uses this renderer.

### `AstroComponentMetadata`

<p>

**Type:** `{ displayName: string; hydrate?: 'load' | 'idle' | 'visible' | 'media' | 'only'; hydrateArgs?: any; componentUrl?: string; componentExport?: { value: string; namespace?: boolean }; astroStaticSlot: true; }`
</p>

An object passed as the fourth argument to a renderer's [`check()`](#ssrloadedrenderervaluecheck) and [`renderToStaticMarkup()`](#ssrloadedrenderervaluerendertostaticmarkup) functions. Contains information about the component being rendered, including its hydration directive.

#### `AstroComponentMetadata.displayName`

<p>

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

The display name of the component, used for error messages and debugging.

#### `AstroComponentMetadata.hydrate`

<p>

**Type:** `'load' | 'idle' | 'visible' | 'media' | 'only' | undefined`
</p>

The [client directive](/en/reference/directives-reference/#client-directives) used on the component, if any. When `undefined`, the component will not be hydrated on the client.

Renderers can use this value to conditionally include client-side hydration state. For example, a renderer can skip serializing transfer state for components that will not be hydrated:

```ts
async function renderToStaticMarkup(Component, props, children, metadata) {
const willHydrate = !!metadata?.hydrate;
// Skip serializing hydration state if the component won't be hydrated
return render(Component, props, { includeTransferState: willHydrate });
}
```

#### `AstroComponentMetadata.hydrateArgs`

<p>

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

Additional arguments for the hydration directive. For example, the value of `client:media="(max-width: 768px)"` would be `"(max-width: 768px)"`. For `client:only="react"`, the value would be `"react"`.

#### `AstroComponentMetadata.componentUrl`

<p>

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

The URL of the component's source file.

#### `AstroComponentMetadata.componentExport`

<p>

**Type:** `{ value: string; namespace?: boolean } | undefined`
</p>

Information about the component's export. The `value` property is the name of the export (e.g. `"default"` for default exports).

#### `AstroComponentMetadata.astroStaticSlot`

<p>

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

Always `true`. Indicates that Astro supports the static slot optimization for this component. Renderers that set [`supportsAstroStaticSlot`](#ssrloadedrenderervaluesupportsastrostaticslot) to `true` can use this in combination with [`hydrate`](#astrocomponentmetadatahydrate) to determine how to render slots.

### `SSRManifest`

An object containing build configuration and project metadata that the server adapters use at runtime to serve on-demand rendered pages.
Expand Down Expand Up @@ -2314,7 +2129,7 @@ Specifies the [configured prefix for Astro-generated asset links](/en/reference/

<p>

**Type:** <code><a href="#ssrloadedrenderer">SSRLoadedRenderer</a>[]</code>
**Type:** <code><a href="/en/reference/renderer-reference/#ssrloadedrenderer">SSRLoadedRenderer</a>[]</code>
</p>

A list of renderers (e.g. React, Vue, Svelte, MDX) available for the server to use.
Expand Down
Loading
Loading