气旋UI - 下一个JS

设置 塔马吉 和“旋风UI”组件在下一个.js中 应用。 软件包有两个切入点:

• @cyclone-ui/nextjs数字 : withCycloneUI,用于 next.config.ts
• @cyclone-ui/nextjs/provider数字 : CycloneUIProvider, 根客户端提供者 带有服务器的光和暗主题

他们跟着 Tamagui Next.js 向导, (中文(简体) ), 使用 @tamagui/next-plugin 财务报告和审定财务报表 @tamagui/next-theme。 。 。 .

快速特性

• 涡轮包装别名 react-native → react-native-web 财务报告和审定财务报表 react-native-svg → @tamagui/react-native-svg
• 用于 Webpack 的 Tamagui 编译器 @tamagui/next-plugin
• 从您自己的设计符号中构建 Tamagui 配置(tokens 选项)
• 定义 process.env.TAMAGUI_TARGET,该“旋风”组件读取 只使用网络样式
• 存储光线、暗光或系统设置,并在水合前应用
• 在服务器渲染过程中收集反应- 内在- 网络样式

安装

使用 小时数字 :

pnpm add @cyclone-ui/nextjs @cyclone-ui/state @cyclone-ui/tokens @tamagui/core jotai react-native-web

添加 @tamagui/react-native-svg 如果应用程序生成 SVG 图标,以及 @tamagui/next-plugin 如果它用Webpack构建.

使用量

环绕下一个.js配置 :

// next.config.ts
import { withCycloneUI } from "@cyclone-ui/nextjs"

export default withCycloneUI({
  reactStrictMode: true
})

包装器还接受承诺的配置或同步/同步 Next.js 配置 函数。 阶段功能仍然懒惰,得到最初阶段和背景; 现有 cacheComponents 财务报告和审定财务报表 partialPrefetching 价值观得到保留.

在根布局中渲染提供者 。 提供者设置一个类 <html> 在反应水合物之前添加 suppressHydrationWarning 这里:

// app/layout.tsx
import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <CycloneUIProvider>{children}</CycloneUIProvider>
      </body>
    </html>
  )
}

版式仍然是服务器组件. 客户端提供者接受服务器发送 孩子们不移动这些 儿童模块到客户端捆绑。 主张 跨越此边界必须可按顺序进行 React 。 默认配置已经 在提供者内部导入; 如果通过自定义 Tamagui config 或一般情况 调用诸如 onChangeTheme,在应用程序所属客户端中定义它们 包装 :

// app/providers.tsx
"use client"

import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
import type { PropsWithChildren } from "react"
import { config } from "@/tamagui.config" // Use your config's actual export.

export function AppProviders({ children }: PropsWithChildren) {
  return <CycloneUIProvider config={config}>{children}</CycloneUIProvider>
}

渲染器 <AppProviders>{children}</AppProviders> 从服务器布局。 这个 构建时间 tokens 选项下还替换提供者的配置导入,所以 它需要没有 config 道具 (英语).

读取或更改主题为 useThemeSetting数字 :

"use client"

import { useThemeSetting } from "@cyclone-ui/nextjs/provider"

export function ThemeToggle() {
  const theme = useThemeSetting()

  return <button onClick={theme.toggle}>Change theme</button>
}

useThemeMode 从 @cyclone-ui/state/theme 返回活动模式. 通过 useThemeSetting数字 : useThemeActions 更改 只有气旋状态,所以选择没有保存.

虽然 forcedTheme 设置,主题更改被屏蔽。 隐藏或禁用 切换被强制的主题; 释放它恢复存储的偏好. 当选定设置时, 系统首选项更改适用 system。 。 。 .

缓存组件和静态贝壳

Next.js 16 中的缓存组件包括部分预发( PPR): 预发 含有动态内容的 shell通过Suspense 流出. 部分预取是 next.js 16.3 引入的单独的导航功能, 需要缓存 组件。 在添加旗帜前检查已安装的 Next.js 版本 。 对于 下一个.js 16.3+,采用这两个特征:

import { withCycloneUI } from "@cyclone-ui/nextjs"

export default withCycloneUI({
  cacheComponents: true,
  partialPrefetching: true
})

withCycloneUI 保留这些选项;它无法在全球范围实现这些选项,或 选择缓存策略。 于下.js 16.0–16.2上省略 partialPrefetching选择 组合 cacheComponents 与老年人 experimental.ppr 旗帜.

保持根布局同步并渲染 CycloneUIProvider 直接围绕 儿童,如上。 提供者不读 cookies() 或者说 headers() 在服务器上。 其内置脚本将已保存或系统主题应用到同一处 水分化前先还原壳. 保持提供者在外部对请求的依赖 悬接边界,所以它及其脚本都包含在外壳中.

在根版式中不要只读取一个主题 cookie mode。 。 。 . mode 实值 (a) SSR/水分回落,而不是用户的持续偏好. modeCookie 实值 可选的客户端写入已解析的光/暗模式的镜像; 它没有 需要服务器 cookie 读取或保存系统和系统之间的区别 明确选择。 将请求改为: cookies(), (中文(简体) ), headers(),以及 searchParams 在需要它们的地方 <Suspense> 带有有用倒计时的边框。 不要把这些读到里面 "use cache" 或者说 把整个供应商都移到边界后面 服务器组件,包括 缓存的,可以作为孩子通过客户端提供者传递.

静态JSX不需要 "use cache"。缓存可重用应用程序数据或服务器 UI 根据其新鲜度和无效性政策; 保持无缝活体工作 在本地悬疑区后面 不将指令添加到客户端提供者或客户端 原始人作为总体优化.

使用语义主题符号和相对分主题,例如 base 在壳里. 避免从浏览器主题偏好中选择服务器标记或字面颜色 . 主题依赖文本从 useThemeSetting().current, (中文(简体) ), resolvedTheme, (中文(简体) ), useRootTheme,或 useThemeMode 必须等到组件上架。 这些 值可以在服务器和第一个浏览器渲染之间有所不同。 不断标签切换 上面不需要护卫 如果显示当前模式标签, 请只注意 标记/控制, 保留其余的外壳. suppressHydrationWarning 打开 <html> 不抑制后代的错配.

启用了部分预取功能, 默认链接预取可重用路由 App 舍所取舍而舍所取一切目的地所取之相. 使用 prefetch={true} 打开 选择的应用程序链接, 也可以解决缓存的 URL 特定内容, 取决于 打开 params, (中文(简体) ), searchParams,或整个URL。 它不再包括无缝 动态内容来自遗留的全部预选; 内容流 : 导航 现有审计 prefetch={true} 在启用旗帜前链接,以及 验证生产中的具体 URL 导航。 避免强制完全预选 在每一个共享链接原始.

见 下一个 Js 缓冲, (中文(简体) ), 采用部分预选, (中文(简体) ), 财务报告和审定财务报表 优化预选。 。 。 .

自定义设计符号

过 tokens 以您自己的设计符号构建 Tamagui 配置 气旋UI默认值。 使用 DTCG 令牌对象,或令牌文件路径或 相对于工作目录的阴影 :

// next.config.ts
import { withCycloneUI } from "@cyclone-ui/nextjs"

export default withCycloneUI(
  { reactStrictMode: true },
  {
    tokens: [
      "tokens/primitives.json",
      "tokens/light.tokens.json",
      "tokens/dark.tokens.json"
    ]
  }
)

有主题名的文件( E)light.tokens.json, (中文(简体) ), dark.tokens.json变成 页:1 light 财务报告和审定财务报表 dark 主题。 符号通过相同的预处理器和 生成器为 @cyclone-ui/tokens,则a razorwind.config.ts 在项目中 仍然适用(例如其字体).

与 tokens 和一个天体的配置, withCycloneUI 返回一个承诺,该承诺 Next.js 接受为配置导出 。 对于相位函数, 符号生成运行 当 Next.js 解决此函数时。 编写仅限第三方对象的包装 在建立标志之前。 配置是写给 .cyclone-ui/tamagui.config.ts (编) .cyclone-ui 改为 .gitignore替换 @cyclone-ui/tokens/tamagui 到处都是,所以 CycloneUIProvider 和Webpack编译器使用. 与 pnpm, Webpack 架构也需要 @tamagui/web 财务报告和审定财务报表 motion 安装在 app,因为 Tamagui 编译器评价生成的配置 项目根.

提供者道具

CycloneUIProvider 接受 NextThemeProvider 道具 (单位:千美元)defaultTheme, (中文(简体) ), forcedTheme, (中文(简体) ), storageKey, (中文(简体) ), enableSystem页:1

网络软件包

next build --webpack 财务报告和审定财务报表 next dev --webpack 运行 Tamagui 编译器通过 @tamagui/next-plugin。安装它,然后通过任何 插件选项 作为第二个论点:

export default withCycloneUI(nextConfig, {
  outputCSS:
    process.env.NODE_ENV === "production"
      ? "./public/tamagui.generated.css"
      : null,
  disableExtraction: process.env.NODE_ENV === "development"
})

默认是 config: "@cyclone-ui/tokens/tamagui", (中文(简体) ), components: ["@tamagui/core"] 财务报告和审定财务报表 appDir: trueA级 tamagui.build.ts 文件 在工程根中覆盖它们.

优化涡轮包装

Turbopack不运行塔马圭编译器. 为了优化生产建设,运行 它与塔玛吉CLI(@tamagui/cli) 之前 next build数字 :

{
  "scripts": {
    "build": "tamagui build --target web ./app -- next build"
  }
}

发展

devenv shell -- pnpm nx run nextjs:build

生产集成钻机用缓存操作源提供者 组件和部分取舍。 从工作空间根, 运行 :

devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test

Playwright 配置构建并自动启动固定, 设置 EXPOSE_TESTING_API=1 用于新建和启动, 使原始的. js 配置可以 启用测试 API。 使用节点22.18+来进行固定配置的TypeScript导入. CHROMIUM_PATH 选择现有的 Chromium 可执行文件; 否则 Playwright 使用已安装的浏览器。 见 即时导航.rig.md 页:1 钻机及其说法.

检查会把请求内容放回原位 检查直接的外壳 装入和客户端导航,然后验证流中的内容到达. 他们也 运行 test/theme.browser.mjs 对抗生产服务器以覆盖 shell CSS 水合之前,坚持偏好,强迫主题,系统变化,饼干, 和延迟水分。 主题检查使用挂载安全诊断标签,因为 共享 shell 无法知道浏览器的存储偏好 .