#服务端渲染

Leaf UI 的基础样式和组件样式会自动加载。下面只介绍各框架需要额外处理的部分，安装和组件用法见快速开始。

#Next.js App Router

全局配置放在 Client Component 中：

'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 配置中加入：

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：

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 的根路由与样式处理。

#首次渲染保持一致

服务端与客户端首次渲染使用相同的主题、语言和初始值。首屏需要深色模式时，从 Cookie 等服务端可读的数据中取得配置；只存在 localStorage 中的偏好，应在挂载后读取。主题和语言的配置方式见定制主题与切换语言。

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

#自行搭建 SSR

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

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

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