chakra-ui-migrate

Chakra UI マイグレーション: v2 → v3

あなたは、開発者がプロジェクトを Chakra UI v2 から v3 へマイグレーションするのをガイドします。以下の手順を順番に進めてください。まずプロジェクトを調査してください — パッケージのバージョンやフレームワークを推測してはいけません。

Node の要件: Chakra UI v3 には Node >= 20.x が必要です。環境が不明な場合は、進める前に確認してください。

---

ステップ 1 — プロジェクトを調査する

現在の状態を把握するために、以下のファイルを読み取ってください:

package.json

以下を確認してください:

• 現在の @chakra-ui/react のバージョン (v2.x か v3.x か)
• 関連パッケージ: @chakra-ui/icons、@chakra-ui/hooks、@chakra-ui/next-js、@emotion/styled、framer-motion
• フレームワーク: Next.js (App Router または Pages Router)、Vite、プレーンな React
• パッケージマネージャー (ロックファイルから: pnpm-lock.yaml、yarn.lock、bun.lock、package-lock.json)

必要に応じて、主要なファイルも抜き取り確認してください:

• Provider / テーマの設定 (_app.tsx、layout.tsx、theme.ts)
• カラーモードの使用箇所 (ColorModeScript、useColorMode、useColorModeValue)
• v2 のパターンが多用されているコンポーネントファイル

---

ステップ 2 — パッケージを更新する

v2 専用の依存関係を削除する

# npm
npm uninstall @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

# pnpm
pnpm remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

# yarn
yarn remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion

@emotion/styled と framer-motion は v3 では不要になりました。

v3 のコアパッケージをインストールする

# npm
npm install @chakra-ui/react @emotion/react

# pnpm
pnpm add @chakra-ui/react @emotion/react

# yarn
yarn add @chakra-ui/react @emotion/react

削除されたパッケージの代替

削除されたもの	代替
@chakra-ui/icons	lucide-react または react-icons
@chakra-ui/hooks	react-use または usehooks-ts
@chakra-ui/next-js	asChild プロップのパターン (Next.js のセクションを参照)

---

ステップ 3 — Codemod を実行する

公式の Codemod は、ほとんどの機械的な変更を処理します: コンポーネント名の変更、プロップの更新、インポートの書き換え、複合コンポーネントの再構築などです。ただし、手動でのレビューが不要になるわけではありません — 出力を監査する予定を立ててください。

まずドライラン (ファイルは変更されません):

npx @chakra-ui/codemod upgrade --dry

提案内容を確認してください。問題がなければ:

npx @chakra-ui/codemod upgrade

Codemod の実行後、手動で編集する前に変更をコミットしてください。そうすれば、作業の基準となるクリーンな差分が得られます。

---

ステップ 4 — Provider を更新する

従来の v2 のパターン

// v2
import { ChakraProvider } from "@chakra-ui/react"
import theme from "./theme"

;<ChakraProvider theme={theme}>{children}</ChakraProvider>

新しい v3 のパターン (Chakra CLI スニペットを使用)

Provider とコンポーネントのスニペットを生成します:

npx @chakra-ui/cli snippet add

これにより components/ui/provider.tsx (toaster と tooltip のスニペットも含む) が作成され、必要な npm 依存関係 (next-themes を含む) が自動的にインストールされます。インポートして使用してください:

// v3 — app/layout.tsx (Next.js App Router)
import { Provider } from "@/components/ui/provider"

;<html lang="en" suppressHydrationWarning>
  <body>
    <Provider>{children}</Provider>
  </body>
</html>

Provider ファイルには "use client" が含まれています — layout.tsx には追加しないでください。Pages Router での配置については Next.js のセクションを参照してください。

v3 でのカスタムテーマ

extendTheme を createSystem に置き換えます:

// v2
import { extendTheme } from "@chakra-ui/react"
// v3
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

export const theme = extendTheme({ colors: { brand: { 500: "#2196f3" } } })

const config = defineConfig({
  theme: { tokens: { colors: { brand: { 500: { value: "#2196f3" } } } } },
})
export const system = createSystem(defaultConfig, config)

system を value={system} を介して ChakraProvider に渡します。

---

ステップ 5 — カラーモードのマイグレーション

v2 のカラーモードパターンをすべて削除する

// REMOVE these v2 imports and usages:
import { ColorModeScript } from "@chakra-ui/react"
// ❌
import { useColorMode } from "@chakra-ui/react"
// ❌ (use next-themes)
import { useColorModeValue } from "@chakra-ui/react"
// ❌ (use CSS tokens)
import { DarkMode, LightMode } from "@chakra-ui/react"

// ❌

// Also remove from _document.tsx:
;<ColorModeScript initialColorMode={theme.config.initialColorMode} /> // ❌

v3 のカラーモードのアプローチ

カラーモードは、生成された Provider を介して next-themes によって処理されます。有効なカラーモードに自動的に応答するセマンティックトークンを使用してください:

// Use Chakra semantic tokens — they flip automatically in dark mode
<Box color="fg.default" bg="bg.subtle">
  ...
</Box>

カラーモードの切り替えには、生成された components/ui/color-mode.tsx スニペット、または next-themes の useColorMode を直接使用してください。

---

ステップ 6 — プロップの名前変更

これらの真偽値プロップとスタイルプロップは、HTML および現代の React の慣習との一貫性のために v3 で名前が変更されました。Codemod はこれらのほとんどを検出しますが、後で手動で確認してください。

真偽値プロップ

v2	v3
isOpen	open
defaultIsOpen	defaultOpen
isDisabled	disabled
isInvalid	invalid
isRequired	required
isReadOnly	readOnly
isChecked	checked
isLoaded	loaded
isIndeterminate	indeterminate

スタイルとレイアウトの props

v2	v3
colorScheme	colorPalette
noOfLines	lineClamp
truncated	truncate
spacing (Stack)	gap
apply	textStyle または layerStyle

ネストされたスタイル props

// v2 — sx with nested pseudo-selectors
<Box sx={{ "&:hover": { color: "blue.500" } }} />

// v3 — css prop with "&" selectors
<Box css={{ "&:hover": { color: "blue.500" } }} />

---

ステップ 7 — コンポーネントの移行

名前が変更されたコンポーネント

v2	v3
Modal	Dialog
FormControl	Field
Select	NativeSelect
AlertDialog	AlertDialog (複合。以下を参照)

Modal は最も一般的な名前変更です — すべての <Modal>、<ModalOverlay>、 <ModalContent>、<ModalHeader>、<ModalBody>、<ModalFooter>、 <ModalCloseButton> が Dialog.* の複合パートになります:

// v2
<Modal isOpen={open} onClose={onClose}>
  <ModalOverlay />
  <ModalContent>
    <ModalHeader>Title</ModalHeader>
    <ModalBody>Body</ModalBody>
    <ModalFooter><Button onClick={onClose}>Close</Button></ModalFooter>
  </ModalContent>
</Modal>

// v3
<Dialog.Root open={open} onOpenChange={({ open }) => setOpen(open)}>
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.Header><Dialog.Title>Title</Dialog.Title></Dialog.Header>
      <Dialog.Body>Body</Dialog.Body>
      <Dialog.Footer><Button onClick={() => setOpen(false)}>Close</Button></Dialog.Footer>
      <Dialog.CloseTrigger />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

複合コンポーネントの書き換え

v3 は一貫した複合コンポーネント API を採用しています。codemod はこれらの多くを 処理しますが、複雑なカスタムの使用法は手動でのレビューが必要です。

Checkbox

// v2
<Checkbox isChecked={val} onChange={fn}>Label</Checkbox>

// v3
<Checkbox.Root checked={val} onCheckedChange={fn}>
  <Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
  <Checkbox.Label>Label</Checkbox.Label>
</Checkbox.Root>

Progress

// v2
<Progress value={60} colorScheme="blue" />

// v3
<Progress.Root value={60} colorPalette="blue">
  <Progress.Track><Progress.Range /></Progress.Track>
</Progress.Root>

Accordion

// v2
<Accordion><AccordionItem><AccordionButton /><AccordionPanel /></AccordionItem></Accordion>

// v3
<Accordion.Root>
  <Accordion.Item value="item-1">
    <Accordion.ItemTrigger />
    <Accordion.ItemContent />
  </Accordion.Item>
</Accordion.Root>

FormControl → Field

// v2
<FormControl isInvalid={!!error} isRequired>
  <FormLabel>Email</FormLabel>
  <Input type="email" />
  <FormErrorMessage>{error}</FormErrorMessage>
  <FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>

// v3
<Field.Root invalid={!!error} required>
  <Field.Label>Email</Field.Label>
  <Input type="email" />
  <Field.ErrorText>{error}</Field.ErrorText>
  <Field.HelpText>We'll never share your email.</Field.HelpText>
</Field.Root>

すべての FormControl のサブパートは Field.* に対応します:

• FormLabel → Field.Label
• FormErrorMessage → Field.ErrorText
• FormHelperText → Field.HelpText
• FormControl の props isInvalid、isRequired、isDisabled → invalid、 required、disabled

Dialog / Drawer / Menu / Tabs も同じ複合パターンに従います: ComponentName.Root、.Trigger、.Content、.Item などを使用します。 それぞれの具体的な複合 API については Chakra UI v3 のドキュメントを確認してください。

Next.js の Image と Link (@chakra-ui/next-js の置き換え)

// v2 — @chakra-ui/next-js
import { LinkOverlay } from "@chakra-ui/next-js"

// v3 — asChild pattern
import NextLink from "next/link"
<ChakraLink asChild><NextLink href="/about">About</NextLink></ChakraLink>

import NextImage from "next/image"
<ChakraImage asChild><NextImage src="..." alt="..." /></ChakraImage>

---

ステップ 8 — テーマの移行

styleConfig と multiStyleConfig → recipes

// v3 — single component (recipe)
import { defineRecipe } from "@chakra-ui/react"

// v2
const buttonStyle = {
  baseStyle: { fontWeight: "bold" },
  variants: { solid: { bg: "blue.500" } },
  defaultProps: { variant: "solid" },
}

const buttonRecipe = defineRecipe({
  base: { fontWeight: "bold" },
  variants: { variant: { solid: { bg: "blue.500" } } },
  defaultVariants: { variant: "solid" },
})

// v3 — slot recipe
import { defineSlotRecipe } from "@chakra-ui/react"

// v2 — multiStyleConfig (multi-part component)
const cardStyle = multiStyleConfig({
  parts: ["root", "header"],
  baseStyle: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})

const cardSlotRecipe = defineSlotRecipe({
  slots: ["root", "header"],
  base: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})

カスタムトークンのための型生成

カスタムトークン、セマンティックトークン、recipes、slot recipes を追加した後は、 型生成を実行して TypeScript の型を同期させてください:

npx @chakra-ui/cli typegen ./theme.ts

複雑なテーマの移行 — 多数のカスタムトークン、セマンティックトークン、 複数パートのコンポーネントスタイルを含む大規模な v2 テーマを移行する場合は、 chakra-ui-theming スキルを使用してください。トークン/recipe/slot-recipe API の 全体を詳細に網羅しており、このセクション単体よりも優れたガイドです。

---

ステップ 9 — Next.js 固有の事項

App Router

• <Provider> を app/layout.tsx に配置します (Server Component — "use client" は不要)
• 生成された components/ui/provider.tsx にはすでに "use client" があります
• カラーモードのちらつきを防ぐため、<html> に suppressHydrationWarning を追加します
• アプリ全体やレイアウト全体を "use client" でラップしないでください

Pages Router

// pages/_app.js
import { Provider } from "@/components/ui/provider"

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

pages/_document.tsx から ColorModeScript を削除してください — v3 では使用されません。

---

ステップ 10 — 検証チェックリスト

移行が完了したら、これを順に進めてください:

• 依存関係を再インストール: npm install / pnpm install
• TypeScript: npx tsc --noEmit — すべての型エラーを解消します
• Lint: npm run lint
• ビルド: npm run build
• カラーモードの切り替え (ライト ↔ ダーク) を目視で確認する
• インタラクティブなコンポーネントをテストする: Dialog、Drawer、Menu、Tabs、Accordion
• フォームコンポーネントをテストする: Checkbox、Select/NativeSelect、Input、Radio
• 主要なページ全体で視覚的なリグレッションがないか確認する
• コードベースに残った v2 のインポートを検索する:

  grep -r "ColorModeScript\|useColorModeValue\|extendTheme\|styleConfig\|@chakra-ui/icons\|@chakra-ui/next-js" src/
  

---

確認のための質問 (コンテキストが不明確な場合)

ユーザーのバージョン、フレームワーク、範囲が曖昧な場合は、次を尋ねてください:

1. 「現在お使いの @chakra-ui/react のバージョンは何ですか?」
2. 「Next.js App Router、Pages Router、Vite、または素の React のどれを使用していますか?」
3. 「コードベース全体を移行しますか、それとも特定のコンポーネントだけですか?」

尋ねずに進める場合は、前提を明確に述べてください。