panda-css-migrate

Panda CSS v1 → v2

v2では記述用APIは維持しつつ、コンパイラーがRustで書き直されています。panda.config.tsはそのまま使えます。主に変更が必要なのは、設定まわり、一部のCLIフラグ、および廃止されたパッケージです。

完全なガイドはUpgrading to v2を参照してください。このスキルでは、手順に沿って進めます。詳しい説明が必要な箇所は、ガイドを確認してください。

始める前に

プロジェクトがv2を実行できることを確認してください。

• ESMのみです。 CommonJSビルドはありません。プロジェクトに"type": "module"を設定するか、.mjsファイルまたはESM対応のバンドラーが必要です。 require('@pandacss/dev')は動作しません。
• Node 22以降が必要です。 公開パッケージでは"engines": { "node": ">=22" }が宣言されています。

どちらかを満たしていない場合は、まず修正してください。設定が読み込めるようになるまでは、ほかの作業は意味がありません。

アップグレードチェックリスト

順番に作業してください。各グループの後にpanda buildを実行します。まとめて作業すると、問題が積み重なります。

1. すべての@pandacss/*パッケージをまとめてv2に更新します。

pnpm add -D @pandacss/dev@latest
pnpm add -D @pandacss/postcss@latest   # or @pandacss/vite, @pandacss/webpack, @pandacss/rollup

v1のパッケージとv2のパッケージを混在させないでください。すべてのパッケージで同じバージョンを使用します。

2. 廃止されたパッケージのインポートを削除します。 機能は@pandacss/compilerに移行されています。対象は@pandacss/core、 @pandacss/extractor、@pandacss/generator、@pandacss/node、@pandacss/parser、@pandacss/token-dictionary、 @pandacss/is-valid-prop、@pandacss/logger、@pandacss/reporter、@pandacss/studioです。プロジェクトで @pandacss/devとバンドラープラグインだけを使っている場合、対応は不要です。

3. プリセットを明示的に追加します。 v2では自動的に挿入されません。プリセットのない設定では、bgや colorのユーティリティ、スペーシングやフォントのスケール、_hoverのない基本システムになります。

export default defineConfig({
  presets: ['@pandacss/preset-base', '@pandacss/preset-panda'],
})

アップグレード後に「すべてが壊れた」と感じる場合、最もよくある原因はこれです。

4. フックをプラグインに移します。

// ❌ v1
hooks: { 'parser:before': handler }

// ✅ v2
plugins: [{ name: 'local', hooks: { 'parser:before': { filter: { id: '**/*.{jsx,tsx}' }, handler } } }]

サポート対象：config:resolved、preset:resolved、parser:before、codegen:prepare、codegen:done、cssgen:done。

廃止：context:created、parser:after、config:change、tokens:created、utility:created、 およびparser:before.configure(...)。cssgen:doneは監視専用になったため、CSS文字列を書き換えることはできません。

未使用のトークンやキーフレームの削除にcssgen:doneを使っていた場合は、代わりにoptimizeを使ってください。

optimize: {
  removeUnusedTokens: true,
  removeUnusedKeyframes: true,
  smartCompoundVariants: true,
}

5. createStyleContextを分割します。 <outdir>/jsxから削除されました。

• Configレシピ（cva）→ createRecipeContext → { withContext }
• Slotレシピ（sva）→ createSlotRecipeContext → { withRootProvider, withProvider, withContext }

6. テンプレートリテラルのスタイルをオブジェクトに変換します。 syntaxオプション、--syntax initフラグ、タグ付きテンプレートによるスタイリングはすべて削除されました。

// ❌ v1
const Button = styled.button`
  padding: 10px 15px;
`

// ✅ v2
const Button = styled('button', { base: { padding: '10px 15px' } })

その後、panda codegen --cleanを実行して、古いランタイムを再生成してください。

7. globalPositionTryを置き換えます。 theme.positionTryとpositionTry()ファクトリーを使ってください。

// ✅ v2
theme: {
  positionTry: {
    bottom: {
      top: 'anchor(bottom)'
    }
  }
}
css({ positionTryFallbacks: positionTry('bottom') })

8. scrollbarWidthを修正します。 現在はsizesトークンではなく、auto | thin | noneを指定します。scrollbarWidth: '4'は常に無効なCSSでした。scrollbarColorに単一のカラートークンを指定している場合は、scrollbarThumbに移します。

9. CLIの使い方を更新します。

• panda inspect、panda validate、panda info → panda doctor（スクリプトでは--jsonを追加）
• panda ship → panda libに変更し、利用側で設定のdesignSystemを指定
• panda mcp / panda init-mcp → npx -y @pandacss/mcp
• --cpu-prof → --profile（.panda/trace.jsonと.panda/timings.jsonを書き出します）
• --silent / --quiet / --verbose → --log-level silent|error|warn|info|debug
• 共通フラグはケバブケースです：--max-warnings、--watch-debounce、--trace-output、--trace-file

10. デザインシステムの接続方法を変更します。 panda shipでライブラリを公開または利用していた場合：

// consumer config
export default defineConfig({ designSystem: '@acme/design-system' })

ビルド情報をincludeに指定しないでください。panda buildを実行した後、ローカルのoutdirからスタイルをインポートします。

11. ビルドを実行して診断情報を確認します。 panda buildを実行し、その後panda doctorを実行します。問題があるように見える場合は、<outdir>/debugにあるpanda debugのダンプで、新しいエンジンが抽出した内容を正確に確認できます。

CSS に変更があった場合

v2 は v1 との同等性を目指しています。以下の違いは意図的なものなので、バグを報告する前に確認してください。

• ボーダーとショートハンドの上書き。 アトミックルールはソースの順序ではなく、プロパティの適用範囲の広さで並べ替えられます。全辺に適用されるショートハンドが、辺ごとの上書きより優先されるようになりました。上書きを優先させるにはロングハンドを使ってください。たとえば、borderInlineEnd: '0' ではなく、borderInlineEndWidth: '0' を使います。
• 複合バリアントは @layer recipes.compound_variants 内の名前付きクラスとして、すべて出力されます。使用する組み合わせだけを出力するには、optimize.smartCompoundVariants: true を設定してください。
• 汎用的な変数リセットはありません。 v1 では、--translate-x や --blur などがすべての要素に設定されていました。v2 では @property を使って登録します。@property をサポートしないエンジンを対象にする場合は、optimize.propertyFallback: true を設定してください。
• ブレークポイントには範囲構文を使用します。 @media (width >= 48rem)。px と em は rem に正規化されます。
• プレフィックス付きの宣言が先に来ます（mask-image より前に -webkit-mask-image）。
• 未使用の @property 登録は削除されます。 登録された変数を参照する唯一の CSS が Panda のスキャン対象外の場合は、その変数を globalCss にも宣言してください。
• 宣言が同一の隣接ルールは統合され、同じ @media または @supports のラッパーを共有するルールはグループ化されます。

いくつかの箇所（たとえばタイポグラフィのショートハンド）でクラス名が変わりました。生成されたクラス名を検証対象にしないでください。

破損ではなく、変更された点

アップグレード後に以下のいずれかが見つかっても、新たに導入したリグレッションではありません。

• Astro ベースの Studio は廃止されました。CLI で生成する代替ツールが予定されています。
• 一部のコミュニティプリセット（preset-atlaskit、preset-open-props）とスタンドアロンプラグインは移植されていません。コミュニティ製のタイポグラフィプリセットの代わりに、ファーストパーティの @pandacss/preset-typography を使用してください。デフォルトのサイズは base ではなく md です。
• @pandacss/postcss でビルドが正常に動作しない場合は、バグを報告する前に Vite プラグインまたは単純な panda build を試し、原因を切り分けてください。

正常に動作している状態

• 書き換える必要のなかった設定で panda build が診断メッセージなしに完了する。
• presets が明示的に設定され、bg などのユーティリティや _hover などの条件が再び解決される。
• @pandacss/core、@pandacss/node、または統合された他のパッケージをインポートしていない。
• 設定のルートに hooks キーがなく、createStyleContext の呼び出しも残っていない。
• v1 との差分に含まれる CSS が、上記の意図的な違いだけである。

関連項目

• 詳細ガイド：v2 へのアップグレード。
• アップグレード後のスタイルの作成：「panda-css」を指定して Skill ツールを呼び出します。
• トークンとレシピのアーキテクチャ：「panda-css-theming」を指定して Skill ツールを呼び出します。