Next.js(Pages)에서 Chakra UI 사용하기

Next.js(Pages)에서 Chakra UI 사용하기 (Using Chakra UI in Next.js Pages)

Next.js pages 디렉터리에 Chakra UI를 설치하는 방법을 안내하는 가이드예요. Next.js 15와 16에서 동작합니다. 스니펫과 원시 컴포넌트를 사용해 더 빠르게 UI를 구축할 수 있습니다.

출처: 문서

본문

호환성 (Compatibility)

Chakra UI는 Next.js 15와 16에서 동작해요.

Chakra UI는 특정 Next.js 메이저 버전에 묶여 있지 않아요. 프로젝트가 지원되는 React와 Emotion 버전을 사용한다면 이 가이드가 적용됩니다.

이 리포지토리의 템플릿은 안정성을 위해 이전 Next.js 메이저를 고정할 수도 있어요. 앱에서 next를 최신 메이저로 업그레이드할 수 있습니다.

템플릿 (Templates)

빠르게 시작하려면 다음 템플릿 중 하나를 사용하세요. 템플릿은 Chakra UI를 사용하도록 올바르게 구성되어 있어요.

설치 (Installation)

최소 Node 버전은 Node.20.x입니다.

의존성 설치 (Install dependencies)

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

스니펫 추가 (Add snippets)

스니펫은 UI를 더 빨리 구축하는 데 사용할 수 있는 사전 빌드된 컴포넌트예요. @chakra-ui/cli를 사용해 스니펫을 프로젝트에 추가할 수 있습니다.

npx @chakra-ui/cli snippet add

tsconfig 업데이트 (Update tsconfig)

TypeScript를 사용한다면 tsconfig 파일의 compilerOptions에 다음 옵션을 포함하도록 업데이트해야 해요.

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

JavaScript를 사용한다면 jsconfig.json 파일을 만들고 위 코드를 파일에 추가하세요.

provider 설정 (Setup provider)

애플리케이션 루트에서 Provider 컴포넌트로 애플리케이션을 감싸세요.

이 provider는 다음을 조합해요.

  • 스타일링 시스템을 위한 @chakra-ui/react의 ChakraProvider
  • 컬러 모드를 위한 next-themes의 ThemeProvider
import { Provider } from "@/components/ui/provider"

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

pages/_document.tsx 파일의 html 요소에 suppressHydrationWarning prop을 추가하세요.

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

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

번들 최적화 (Optimize Bundle)

실제로 사용하는 모듈만 로드해 번들 크기를 최적화하려면 Next.js의 experimental.optimizePackageImports 기능을 사용하는 것을 권장해요.

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

이것은 다음과 같은 경고를 해결하는 데도 도움이 됩니다.

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

하이드레이션 오류 (Hydration errors)

Hydration failed because the initial server rendered HTML did not match the client 같은 오류가 보이고 그 오류가 다음과 유사하다면:

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

이것은 Turbopack으로 실행할 때 Next.js가 Emotion CSS를 하이드레이션하는 방식 때문에 발생해요. package.json 파일의 dev와 build 스크립트에 --webpack 플래그를 대신 추가하세요.

- "dev": "next dev"
- "build": "next build"
+ "dev": "next dev --webpack"
+ "build": "next build --webpack"

Next.js 팀이 이 문제를 수정하면 이 가이드를 업데이트할게요.

즐거운 개발 되세요! (Enjoy!)

Chakra UI의 스니펫과 원시 컴포넌트의 힘으로 더 빠르게 UI를 구축할 수 있어요.

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

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

더 알아보기 (Learn more)