> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/en/guide/ssr.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms-full.txt.

# Server-side rendering

Leaf UI loads its base and component styles automatically. This page covers only framework-specific setup. See [quick start](https://ifhover.github.io/leaf-ui/v/0.6.0/en/guide/getting-started.md) for installation and component usage.

## Next.js App Router

Put application-wide configuration in a Client Component:

```tsx title="app/providers.tsx"
'use client';

import { ConfigProvider } from '@ifhover/leaf-ui';
import type { ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  return <ConfigProvider>{children}</ConfigProvider>;
}
```

In your existing `app/layout.tsx`, wrap `{children}` inside `<body>` with `Providers`. Keep the layout itself as a Server Component.

Business components with event handlers, hooks or interactive state also need `'use client'`. Client Components still participate in server prerendering; there is no need to set `ssr: false`.

## Next.js Pages Router

Place application-wide configuration in `pages/_app.tsx`. No `'use client'` directive is needed.

For Webpack builds, add this option to your existing Next.js configuration:

```js title="next.config.mjs"
export default {
  transpilePackages: ['@ifhover/leaf-ui'],
};
```

Append the package if you already have `transpilePackages`, then restart the development server. This lets Next.js process CSS inside the library and avoids the global CSS import error from `node_modules`. The option requires Next.js 13 or later.

The default Turbopack build in Next.js 16.4.1 needs no extra configuration. Neither build requires manual Leaf UI stylesheet imports.

## TanStack Start

Use the default Vite setup. For application-wide configuration, wrap `Outlet` in your existing root route, `src/routes/__root.tsx`:

```tsx title="src/routes/__root.tsx"
import { ConfigProvider } from '@ifhover/leaf-ui';
import { Outlet } from '@tanstack/react-router';

function RootComponent() {
  return (
    <RootDocument>
      <ConfigProvider>
        <Outlet />
      </ConfigProvider>
    </RootDocument>
  );
}
```

Keep your project's existing `RootDocument` and the other root route options. `HeadContent` in `<head>` renders the initial stylesheet links; `Scripts` in `<body>` loads the client scripts. Start discovers component styles in the build output, so Leaf UI needs no explicit `?url` stylesheet link or `'use client'` directive.

See TanStack Start's [root route](https://tanstack.com/start/latest/docs/framework/react/guide/routing) and [CSS styling](https://tanstack.com/start/latest/docs/framework/react/guide/css-styling) guides.

## Keep the first render consistent

Use the same theme, language and initial values on the server and during client hydration. For dark mode on the first frame, read configuration from a Cookie or other server-readable data. Read preferences stored only in `localStorage` after mounting. See [theming](https://ifhover.github.io/leaf-ui/v/0.6.0/en/guide/theming.md) and [switch languages](https://ifhover.github.io/leaf-ui/v/0.6.0/en/guide/internationalization.md) for configuration.

Pass consistent initial values to dates, times and countdowns too; avoid separate `new Date()` calls for each side's initial render. Popups such as Modal and Message appear after mounting on the client.

## Custom SSR

When rendering directly with Node without framework-managed stylesheet discovery, import the full static stylesheet in the entry that builds your browser assets:

```ts
import '@ifhover/leaf-ui/styles/all.css';
```

Include the emitted CSS link in the initial HTML. The Node component entry does not import CSS and can be used directly for server rendering.