Skip to Content
文档

在 Next.js（页面）中使用 Chakra UI

Chakra UI 在 Next.js 页面目录下的安装指南

模板

¥Templates

使用以下模板之一快速入门。模板已正确配置以使用 Chakra UI。

¥Use one of the following templates to get started quickly. The templates are configured correctly to use Chakra UI.

Next.js app template

Next.js pages template

安装

¥Installation

所需的最低 Node 版本为 Node.20.x

1

安装依赖

¥Install dependencies

npm i @chakra-ui/react @emotion/react
2

添加代码片段

¥Add snippets

代码片段是预先构建的组件，你可以使用它们更快地构建 UI。使用 @chakra-ui/cli 属性，你可以将代码片段添加到你的项目中。

¥Snippets are pre-built components that you can use to build your UI faster. Using the @chakra-ui/cli you can add snippets to your project.

npx @chakra-ui/cli snippet add
3

更新 tsconfig

¥Update tsconfig

如果你使用的是 TypeScript，则需要更新 tsconfig 文件中的 compilerOptions，使其包含以下选项：

¥If you're using TypeScript, you need to update the compilerOptions in the tsconfig file to include the following options:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

如果你使用 JavaScript，请创建一个 jsconfig.json 文件并将上述代码添加到该文件中。

4

设置提供者

¥Setup provider

使用 Provider 组件封装你的应用，并将其置于应用的根目录。

¥Wrap your application with the Provider component at the root of your application.

此提供程序包含以下内容：

¥This provider composes the following:

  • ChakraProvider 来自 @chakra-ui/react，用于样式系统

  • ThemeProvider 来自 next-themes，用于颜色模式

pages/_app.tsx

import { Provider } from "@/components/ui/provider"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

在 pages/_document.tsx 文件中，将 suppressHydrationWarning 属性添加到 html 元素。

¥In the pages/_document.tsx file, add the suppressHydrationWarning prop to the html element.

pages/_document.tsx

import { Head, Html, Main, NextScript } from "next/document"

export default function Document() {
  return (
    <Html suppressHydrationWarning>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
5

优化包

¥Optimize Bundle

我们建议使用 Next.js 中的 experimental.optimizePackageImports 功能，通过仅加载实际使用的模块来优化包大小。

¥We recommend using the experimental.optimizePackageImports feature in Next.js to optimize your bundle size by loading only the modules that you are actually using.

next.config.mjs

export default {
  experimental: {
    optimizePackageImports: ["@chakra-ui/react"],
  },
}

这也有助于解决以下警告：

¥This also helps resolve warnings like:

[webpack.cache.PackFileCacheStrategy] Serializing big strings (xxxkiB)
6

水合错误

¥Hydration errors

如果你看到如下错误：Hydration 失败，因为初始服务器渲染的 HTML 与客户端不匹配，错误类似于：

¥If you see an error like this: Hydration failed because the initial server rendered HTML did not match the client, and the error looks similar to:

+<div className="chakra-xxx">
-<style data-emotion="css-global xxx" data-s="">

这是由 Next.js 在 --turbo 模式下如何整合 Emotion CSS 造成的。请从 package.json 文件中的 dev 脚本中删除 --turbo 标志。

¥This is caused by how Next.js hydrates Emotion CSS in --turbo mode. Please remove the --turbo flag from your dev script in your package.json file.

- "dev": "next dev --turbo"
+ "dev": "next dev"

当 Next.js 团队修复此问题后，我们将更新本指南。

¥When this is fixed by the Next.js team, we'll update this guide.

7

尽情享受吧！

¥Enjoy!

借助 Chakra UI 的代码片段和原始组件的强大功能，你可以更快地构建 UI。

¥With the power of the snippets and the primitive components from Chakra UI, you can build your UI faster.

import { Button, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack>
      <Button>Click me</Button>
      <Button>Click me</Button>
    </HStack>
  )
}

Previous

Next.js（应用）

Next

Remix