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

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

# 服务端渲染

Leaf UI 的基础样式和组件样式会自动加载。下面只介绍各框架需要额外处理的部分，安装和组件用法见[快速开始](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/getting-started.md)。

## Next.js App Router

全局配置放在 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>;
}
```

在已有的 `app/layout.tsx` 中，用 `Providers` 包裹 `<body>` 内的 `{children}`。布局本身保留为 Server Component。

含事件回调、hooks 或交互状态的业务组件也要声明 `'use client'`。Client Component 仍会参与服务端预渲染，无需设置 `ssr: false`。

## Next.js Pages Router

全局配置放在 `pages/_app.tsx`，无需声明 `'use client'`。

使用 Webpack 构建时，在现有 Next.js 配置中加入：

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

已有 `transpilePackages` 时追加包名，修改后重启开发服务。它让 Next.js 处理组件库内部的 CSS，避免“不能从 node_modules 内导入全局 CSS”的错误。此选项需要 Next.js 13 或以上。

Next.js 16.4.1 的默认 Turbopack 构建无需这项额外配置。两种构建方式都无需手动导入 Leaf UI 样式。

## TanStack Start

使用默认 Vite 配置即可。需要全局配置时，在已有根路由 `src/routes/__root.tsx` 中包裹 `Outlet`：

```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>
  );
}
```

`RootDocument` 沿用项目已有的文档组件，根路由的其他配置保持不变。`<head>` 中的 `HeadContent` 输出首屏样式链接，`<body>` 中的 `Scripts` 加载客户端脚本。Start 会从构建产物中发现组件样式，无需为 Leaf UI 添加 `?url` 样式链接或 `'use client'`。

详见 TanStack Start 的[根路由](https://tanstack.com/start/latest/docs/framework/react/guide/routing)与[样式处理](https://tanstack.com/start/latest/docs/framework/react/guide/css-styling)。

## 首次渲染保持一致

服务端与客户端首次渲染使用相同的主题、语言和初始值。首屏需要深色模式时，从 Cookie 等服务端可读的数据中取得配置；只存在 `localStorage` 中的偏好，应在挂载后读取。主题和语言的配置方式见[定制主题](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/theming.md)与[切换语言](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/internationalization.md)。

日期、时间和倒计时也应传入一致的初值；避免两端分别用 `new Date()` 生成初值。Modal、Message 等浮层在客户端挂载后显示。

## 自行搭建 SSR

直接使用 Node 渲染、未通过框架收集页面样式时，在负责生成浏览器资源的入口引入完整静态样式：

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

将输出的 CSS 链接加入首屏 HTML。Node 的组件入口不导入 CSS，可以直接用于服务端渲染。