React

The React adapter routes dashed JSX tags through a CustomElement wrapper. On the server, the wrapper calls the registered renderer and emits declarative shadow DOM. On the client, React renders the host tag; the browser has already parsed the shadow template.

Install

pnpm add @svebcomponents/ssr @svebcomponents/ssr-react svelte

Configure

Point the automatic JSX transform at the adapter:

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@svebcomponents/ssr-react",
  },
}

For the Next.js App Router, follow the Next.js guide.

Import browser and server entries

Import the component package from code that runs in the browser:

// client entry
import "my-component-package";

Register its renderer from the server entry:

// server entry
import "my-component-package/ssr";

Keep the /ssr import out of client modules.

Render

Write the element as JSX:

<my-component title="Hello" count={5} />

To keep React’s default JSX runtime, use the wrapper component:

import { CustomElement } from "@svebcomponents/ssr-react";

<CustomElement tag="my-component" title="Hello" count={5} />;

Async components

React’s renderToString cannot await a custom-element renderer. The default wrapper emits the host tag without shadow content for an async element. Svelte mounts the component when the element upgrades.

A React Server Component can await the renderer:

import { CustomElement } from "@svebcomponents/ssr-react/rsc";

<CustomElement tag="my-component" title="Hello" count={5} />;

In a React Server Component, plain dashed tags automatically support async rendering. Import /rsc only when you want to use the wrapper explicitly. Client Components and plain React SSR use the default wrapper. Enable compilerOptions.experimental.async in the component package when the Svelte component itself awaits during rendering.

An async preparation hook needs the /rsc wrapper but does not require Svelte’s async compiler mode.

Read Async components and server data for the package-side choices.

Limits

• The adapter supports React 19.
• The default wrapper server-renders synchronous element renderers.
• The async wrapper works in React Server Components.
• The JSX runtime recognizes custom-element names by their dash.

See the @svebcomponents/ssr-react reference for exports and fallback behavior.