# @cyclone-ui/nextjs 中文文档

规范地址：https://npmcn.com/package/%40cyclone-ui/nextjs/

版本：0\.0\.39
npm 元数据更新时间：2026-11-10T16:58:29.382Z
中文译文更新时间：2026-11-11T07:04:03.953Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyclone-ui/nextjs
原文对照：https://npmcn.com/package/%40cyclone-ui/nextjs/?lang=original
项目主页：https://github.com/storm-software/cyclone-ui#readme
源码仓库：https://github.com/storm-software/cyclone-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：71 kB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：next ^16\.4\.5，react ^19\.3\.1，react-native ^0\.87\.1，@tamagui/core 3\.2\.0，react-native-web 0\.19\.12，@cyclone-ui/state ^0\.0\.68，@cyclone-ui/tokens ^0\.3\.54，@tamagui/next-plugin 3\.2\.0，@tamagui/react-native-svg 3\.2\.0
- 首次发布：2026-10-24T11:16:39.970Z
- 最新版本发布：2026-11-10T16:58:29.037Z
- 近 30 天下载量：6329（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

A Next.js 配置包和根提供商,在 Next.js 应用程序中设置了 Tamagui 和 Cyclone UI 组件.

## 安装

```sh
npm install @cyclone-ui/nextjs
```

也可以使用：`pnpm add @cyclone-ui/nextjs`、`yarn add @cyclone-ui/nextjs`、`bun add @cyclone-ui/nextjs`

## README

# 气旋UI - 下一个JS

设置 [塔马吉](https://tamagui.dev/) 和“旋风UI”组件在下一个.js中 应用。 软件包有两个切入点:

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

他们跟着 [Tamagui Next.js 向导](https://tamagui.dev/docs/guides/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`,该“旋风”组件读取 只使用网络样式
-   存储光线、暗光或系统设置,并在水合前应用
-   在服务器渲染过程中收集反应- 内在- 网络样式

## 安装

使用 [小时](http://pnpm.io/)数字 :

```bash
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配置 :

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

export default withCycloneUI({
  reactStrictMode: true
})
```

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

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

```tsx
// 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`,在应用程序所属客户端中定义它们 包装 :

```tsx
// 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`数字 :

```tsx
"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+,采用这两个特征:

```ts
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 缓冲](https://nextjs.org/docs/app/getting-started/caching), (中文(简体) ), [采用部分预选](https://nextjs.org/docs/app/guides/adopting-partial-prefetching), (中文(简体) ), 财务报告和审定财务报表 [优化预选](https://nextjs.org/docs/app/guides/optimizing-prefetching)。 。 。 .

### 自定义设计符号

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

```ts
// 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` 道具](https://tamagui.dev/docs/guides/next-js#themes) (单位:千美元)`defaultTheme`, (中文(简体) ), `forcedTheme`, (中文(简体) ), `storageKey`, (中文(简体) ), `enableSystem`页:1

| Prop | 默认 | 说明 |
| --- | --- | --- |
| `config` | 配置来自 `@cyclone-ui/tokens/tamagui` | Tamagui 配置; 在客户端包中导入自定义配置 |
| `disableInjectCSS` | `false` | 当应用程序导入 Tamagui 编译器生成的 CSS 时跳过运行时间主题 CSS |
| `skipNextHead` | `true` | 将主题脚本内置. 设定 `false` 在要使用的页路由器中 `next/script` |
| `mode` | `"light"` | 服务器共享的倒置模式和初始客户端渲染 |
| `modeCookie` | —— 说 | 包含解析模式的可选客户端写 cookie |

### 网络软件包

`next build --webpack` 财务报告和审定财务报表 `next dev --webpack` 运行 Tamagui 编译器通过 `@tamagui/next-plugin`。安装它,然后通过任何 [插件选项](https://tamagui.dev/docs/guides/next-js#older-versions-webpack) 作为第二个论点:

```ts
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: true`A级 `tamagui.build.ts` 文件 在工程根中覆盖它们.

### 优化涡轮包装

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

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

## 发展

```bash
devenv shell -- pnpm nx run nextjs:build
```

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

```bash
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](https://npmcn.com/package/%40cyclone-ui/nextjs/instant-nav.rig.md) 页:1 钻机及其说法.

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

## 常见问题

### @cyclone-ui/nextjs 是什么？

A Next\.js 配置包和根提供商,在 Next\.js 应用程序中设置了 Tamagui 和 Cyclone UI 组件\.

### 如何安装 @cyclone-ui/nextjs？

在项目目录运行 npm install @cyclone-ui/nextjs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（^16\.4\.5）、react（^19\.3\.1）、@tamagui/core（3\.2\.0）、react-native-web（0\.19\.12）、@cyclone-ui/state（^0\.0\.68）、@cyclone-ui/tokens（^0\.3\.54）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cyclone-ui/nextjs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyclone-ui/nextjs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cyclone-ui/nextjs 可以商用吗？

@cyclone-ui/nextjs 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cyclone-ui/nextjs 的下载量有多少？

根据 npm 官方下载统计，@cyclone-ui/nextjs 在 2026/10/11 – 2026/11/09 这 30 天内被下载 6,329 次，日均约 211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyclone-ui/nextjs 还在维护吗？

最新版本 0\.0\.39 发布于 2026/11/11（今天）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2026/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。