在 Next.js (Pages) 中使用 Chakra UI
在 Next.js pages 目录下安装 Chakra UI 的指南
模板
使用以下模板之一快速开始。这些模板已正确配置，可与 Chakra UI 配合使用。
安装
所需的最低 Node 版本为 Node.20.x
1
安装依赖
npm i @chakra-ui/react @emotion/react2
3
更新 tsconfig
如果您正在使用 TypeScript，您需要更新 tsconfig 文件中的 compilerOptions 以包含以下选项
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Bundler",
"skipLibCheck": true,
"paths": {
"@/*": ["./src/*"]
}
}
}如果您正在使用 JavaScript，请创建一个 jsconfig.json 文件并将上述代码添加到该文件中。
4
设置 Provider
在您应用程序的根部，使用 Provider 组件包装您的应用程序。
此 Provider 包含以下组件
- 用于样式系统的
@chakra-ui/react中的ChakraProvider - 用于颜色模式的
next-themes中的ThemeProvider
pages/_app.tsx
import { Provider } from "@/components/ui/provider"
export default function App({ Component, pageProps }: AppProps) {
return (
<Provider>
<Component {...pageProps} />
</Provider>
)
}在 pages/_document.tsx 文件中，为 html 元素添加 suppressHydrationWarning 属性。
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
优化打包
我们建议在 Next.js 中使用 experimental.optimizePackageImports 功能来优化您的打包大小，仅加载您实际使用的模块。
next.config.mjs
export default {
experimental: {
optimizePackageImports: ["@chakra-ui/react"],
},
}这也有助于解决以下警告
[webpack.cache.PackFileCacheStrategy] Serializing big strings (xxxkiB)6
水合错误
如果您看到类似以下的错误水合失败，因为初始服务器渲染的 HTML 与客户端不匹配，且错误类似于
+<div className="chakra-xxx">
-<style data-emotion="css-global xxx" data-s="">这是由于 Next.js 在 --turbo 模式下水合 Emotion CSS 的方式造成的。请从您的 package.json 文件中的 dev 脚本中移除 --turbo 标志。
- "dev": "next dev --turbo"
+ "dev": "next dev"当 Next.js 团队修复此问题后，我们将更新此指南。
7
尽情体验！
借助 Chakra UI 的代码片段和基础组件的力量，您可以更快地构建 UI。
import { Button, HStack } from "@chakra-ui/react"
const Demo = () => {
return (
<HStack>
<Button>Click me</Button>
<Button>Click me</Button>
</HStack>
)
}