---
title: "Component SSR"
description: "Server-render Radiant Element Hosts through the explicit server pipeline."
order: 3
---

# Component SSR

Radiant component SSR is an **opt-in server pipeline**. It is light-DOM first, runs in-process on Node with `AsyncLocalStorage` for ambient render state, and does not use a Lit-style render worker.

## Install once at server boot

```ts
import { radiantSsrRuntimeInstalled } from '@ecopages/radiant/server/install-ssr-runtime';

void radiantSsrRuntimeInstalled;
```

That side-effect install wires the light-DOM shim and JSX SSR scope adapters. When bundling Nitro/Vite SSR, keep `@ecopages/*` **external** so Node resolves one module instance for ALS and adapters.

Then render:

```ts
import { renderComponent } from '@ecopages/radiant/server/render-component';

const rendered = await renderComponent(MyCard, {
	initialize: (card) => {
		card.count = 3;
	},
	authoredContent: '<p>Projected</p>',
	renderOptions: { mode: 'hydrate' },
});

// rendered.markup — host HTML
// rendered.metadata — tagName, assets, generatedAt
// rendered.preview — JSX-compatible embed value
```

When `ssrContext` supplies a consumed context, `renderComponent` resolves it before `initialize` runs. A `renderController` call inside an active provider context does the same. Use either callback to derive initial host state from the consumed value.

## From request to hydrated page

```mermaid
flowchart LR
  Boot[Install the SSR runtime] --> Data[Await data first]
  Data --> Render[renderComponent]
  Render --> Html[HTML with data-radiant-ssr]
  Html --> Upgrade[Browser upgrades hosts]
  Upgrade --> Hydrate[Hydrator attaches]
```

## Surfaces

| Need | API |
| --- | --- |
| Adapter / fragment HTML | `renderComponent` / `renderComponentToString` from `@ecopages/radiant/server/render-component` |
| Lower-level host string | `renderRadiantElementHostToString` from `@ecopages/radiant/server/radiant-element-ssr` |
| View-only string | `renderRadiantElementViewToString(element, options)` from `@ecopages/radiant/server/radiant-element-ssr` |

There is no durable Element Host instance API named `renderHostToString()`.

JSX still accepts third-party custom elements that implement `renderHostToString(...)` on the instance. Radiant Element Hosts do not use that path; they go through the installed server custom-element render hook and the APIs above.

## Light DOM only

Radiant renders into light DOM only, on the client and on the server. There is no shadow render mode and no declarative shadow DOM output.

## Async boundary

Resolve data and assets **outside** the SSR render scope. Enter ALS-backed scope only for the synchronous render snapshot. Await I/O before `renderComponent` / `renderToString`, not inside `render()`.

## Hydration follow-up

Pair SSR markup with the client hydrator:

```ts
import '@ecopages/radiant/client/install-hydrator';
```

See [Hydration](/docs/ssr/hydration) and [JSX SSR](/docs/ssr/jsx-ssr).

## Minimal DOM queries during SSR

Node SSR installs a lightweight DOM shim, not a full browser. Component code that runs while a host serializes — for example `this.querySelector('[data-ref]')`, `this.closest('rui-disclosure-group')`, or `@query` / `getRef(...)` — relies on that shim.

**Supported:** tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, descendant and child combinators, comma-separated lists.

**Unsupported:** pseudo-classes (`:not`, `:has`, …), pseudo-elements, sibling combinators, shadow-root queries. Every unsupported selector throws `SyntaxError`: a pseudo-class or pseudo-element wherever it is written (`:not(...)`, `.card:hover`, `p:first-child`, `a:hover`, `p::before`), sibling combinators (`+`, `~`), and malformed attribute selectors. Write a namespaced tag with an escaped colon, `svg\:rect`, as in a browser. Query with tags, ids, classes and attributes.

Author light DOM with `authoredContent` / `prepareHost` before the first server render when lifecycle code needs to query slotted or projected nodes. See the package server README for the full supported surface.
