shadcn/ui v4完全解説｜CLI・AI連携・移行ガイド2026

「shadcn/uiってコンポーネントコピーするだけのツールじゃないの？」

そう思っていたのは、つい先月の話です。2026年3月、shadcn CLIがv4に進化し、話の前提が根本から変わりました。単なるUIコンポーネントのインストーラーから、AIエージェントと協調して動く「プロジェクト状態管理ツール」へ。GitHubスター数100,000を超え、Vercel・Supabaseといった大手が採用するshadcn/uiが、2026年のUI開発をどう再定義するのか解説します。

この記事では、CLI v4の新機能、AIエージェント連携「shadcn/skills」、Design System Presets、Tailwind v4との統合、そしてv3からの移行手順を、コピペ可能なコマンド例つきで全公開します。今日すぐ試せるところから順に紹介しますので、ぜひ手を動かしながら読み進めてください。

まず5分で試したい「CLI v4」の即効コマンド3選

shadcn CLI v4で最も実務に効くコマンドから始めましょう。インストール済みのプロジェクトがあれば、今すぐ試せます。

即効コマンド1: –dry-runで変更をプレビュー

コンポーネントを追加する前に、何が変更されるかを安全に確認できます。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

# buttonコンポーネントの変更内容をプレビュー（実際には適用しない）
npx shadcn@latest add button --dry-run

# レジストリの更新差分を確認してから適用するかどうか判断
npx shadcn@latest add button --diff

動作環境: Node.js 18+, shadcn CLI v4以降

これまでは「とりあえず追加してみて、気に入らなければ手動で戻す」という運用が多かったはずです。--dry-runがあれば、チームレビュー前に変更の全体像を把握できます。

即効コマンド2: shadcn docsでCLIから直接ドキュメント取得

コンポーネントのドキュメントをブラウザで開かずに、ターミナルから直接取得できます。

# comboboxのドキュメントとAPIリンクを取得
npx shadcn@latest docs combobox

# dialogのドキュメントを取得
npx shadcn@latest docs dialog

AIエージェントと組み合わせると真価を発揮します。Claude Codeで「comboboxを実装して」と指示したとき、エージェントがshadcn docsを自律的に実行して最新のAPIを参照しながらコードを生成できるようになりました。

即効コマンド3: Design System Presetsを一行で適用

デザインシステム全体（カラー・テーマ・アイコン・フォント）を1コード文字列で共有・適用できます。

# プリセットを指定して新規プロジェクトを初期化
npx shadcn@latest init --preset a1Dg5eFl

# Monorepoプロジェクトにプリセットを適用
npx shadcn@latest init --monorepo --preset a1Dg5eFl

チームで「プリセットコード」を共有するだけで、全員が同じデザインシステム環境を再現できます。デザイントークンの属人化問題が解消される機能です。

shadcn/ui CLI v4の3本柱を整理する

v4の新機能は大きく3つに分類できます。それぞれの役割と実務インパクトを整理しましょう。

AIエージェントの基本概念や設計パターンについては、AIエージェント構築完全ガイドで体系的にまとめています。shadcn/skillsを最大限活用するために合わせて参照してください。

shadcn/skills: AIエージェントとUI開発が融合する

v4の目玉機能です。正直、これは想像以上に便利でした。

これまでClaude CodeやCursorでshadcn/uiを使ったコードを書かせると、コンポーネントのAPI仕様が古かったり、プロジェクトのエイリアス設定を無視したコードが生成されたりしていました。shadcn/skillsはこの問題を根本から解決します。

仕組み: shadcn info –jsonで何を注入するか

shadcn/skillsをインストールすると、AIエージェントは毎回の会話でshadcn info --jsonを実行し、以下の情報をコンテキストとして受け取ります。

# shadcn/skillsのインストール（Claude Code用）
npx skills add shadcn/ui/shadcn

# shadcn info --jsonで出力される情報の例
{
  "framework": "next",
  "tailwind": { "version": "4.x", "config": "css" },
  "aliases": { "components": "@/components", "ui": "@/components/ui" },
  "baseLibrary": "radix",
  "iconLibrary": "lucide",
  "installedComponents": ["button", "dialog", "command", "sidebar"],
  "resolvedPaths": {
    "components": "/Users/dev/myapp/components",
    "ui": "/Users/dev/myapp/components/ui"
  }
}

動作環境: shadcn CLI v4以降, components.jsonが存在するプロジェクト

この情報があることで、AIエージェントは「このプロジェクトはNext.js + Tailwind v4 + Radix UIを使っている。インポートパスは@/components/ui/だ」と正確に把握した上でコードを生成します。

対応AIアシスタント

components.jsonが存在するプロジェクトで作業しているとき、スキルは自動的にアクティベートされます。追加の設定は不要です。

Tailwind v4移行: CSS変数と@themeで設定ファイルが消える

shadcn/ui v4はTailwind CSS v4と完全に統合されています。移行前後の変化を把握しておきましょう。

設定ファイルの変化

/* Tailwind v3: tailwind.config.js が必要だった */
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'hsl(var(--primary))',
      }
    }
  }
}

/* Tailwind v4: globals.css だけで完結する */
/* globals.css */
@import "tailwindcss";
@import "tw-animate-css";  /* tailwindcss-animate から変更 */

@theme {
  --color-primary: oklch(0.55 0.22 264);  /* HSL → OKLCH に移行 */
  --color-primary-foreground: oklch(0.98 0 0);
}

動作環境: Tailwind CSS v4.x, shadcn/ui v4コンポーネント

HSL→OKLCHへの移行は、より広いガモット（色域）と鮮やかな色表現を可能にします。特にP3ディスプレイ対応の際に効果を発揮します。

依存関係の変更

# 旧: tailwindcss-animateを削除
npm uninstall tailwindcss-animate

# 新: tw-animate-cssをインストール
npm install -D tw-animate-css

AIアプリ開発で活きる主要コンポーネント

shadcn/uiはAIアプリケーション開発と相性が抜群です。よく使われる組み合わせを整理します。

AIチャットUIの実装例（Command + Skeleton）

// 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

// AIチャット入力エリアのサンプル実装
// 動作環境: Next.js 15+, React 19, shadcn/ui v4

import { Command, CommandInput } from "@/components/ui/command"
import { Skeleton } from "@/components/ui/skeleton"

type Message = {
  role: "user" | "assistant"
  content: string
  isStreaming?: boolean
}

export function AIChatInput({
  onSubmit,
}: {
  onSubmit: (prompt: string) => void
}) {
  return (
    
       {
          if (e.key === "Enter" && !e.shiftKey) {
            onSubmit(e.currentTarget.value)
          }
        }}
      />
    
  )
}

// ストリーミング中のスケルトン表示
export function StreamingMessage({ isStreaming }: { isStreaming: boolean }) {
  if (isStreaming) {
    return (
      

        
        
        
      
    )
  }
  return null
}

v3→v4移行の実践手順

既存プロジェクトをv3からv4に移行する際の手順をまとめます。移行は段階的に行えます。

Step 1: codemodでforwardRefを自動削除

# React 19対応: forwardRefをprops化する自動変換
npx @shadcn/codemod remove-forward-ref

# 変換前（React 18スタイル）
const Button = React.forwardRef(
  ({ className, ...props }, ref) => (
    
  )
)

# 変換後（React 19スタイル）
const Button = ({ className, ref, ...props }: ButtonProps & {
  ref?: React.RefObject
}) => (
  
)

Step 2: 依存関係の更新

# アニメーション依存の差し替え
npm uninstall tailwindcss-animate
npm install -D tw-animate-css

# globals.cssの@importを更新
# 変更前: @import "tailwindcss-animate";
# 変更後: @import "tw-animate-css";

Step 3: migrate コマンドで自動移行

# shadcn/ui v4への自動移行（既存コンポーネント更新）
npx shadcn migrate

# 移行前にdry-runで確認
npx shadcn migrate --dry-run

移行チェックリスト

Monorepoファーストサポートの実際

CLI v4はモノレポ構成を正式にサポートしました。複数パッケージを管理するプロジェクトでの利用が大幅に楽になります。

# モノレポ対応の初期化
npx shadcn@latest init --monorepo

# モノレポ内の特定パッケージにコンポーネントを追加
npx shadcn@latest add button --cwd packages/ui

# モノレポでdesign system presetsを適用
npx shadcn@latest init -t next --monorepo --preset a1Dg5eFl

動作環境: pnpm workspaces, turborepo等のモノレポ構成

これまではルートのcomponents.jsonがパッケージ境界を正しく認識せず、インポートパスが壊れることがありました。--monorepoフラグによって、各パッケージのスコープを正確に把握した上でファイルを配置してくれます。

【要注意】よくある失敗パターンと回避策

失敗1: Tailwind v3とv4を混在させる

❌ よくある間違い: tailwind.config.jsを残したままglobals.cssに@themeを追加する

⭕ 正しいアプローチ: Tailwind v4移行時はtailwind.config.jsを削除し、設定をglobals.cssの@themeディレクティブに完全移行する

なぜ重要か: 設定が競合すると、カラートークンが意図しない値で上書きされます。特に--primary等の変数は両方に存在できてしまうため、どちらが有効かデバッグが困難になります。

失敗2: shadcn/skillsのインストールを忘れてAIに頼む

❌ よくある間違い: components.jsonが存在するのにskillsをインストールせず、AIにコード生成を依頼する

⭕ 正しいアプローチ: 新規プロジェクト開始時に必ずnpx skills add shadcn/ui/shadcnを実行する

なぜ重要か: skillsなしでは、AIエージェントはプロジェクトのインポートパスやインストール済みコンポーネントを知らずにコードを生成します。動かないコードの修正に時間を取られます。

失敗3: toastをsonnerに移行せずそのまま使う

❌ よくある間違い: v4移行後も旧toastコンポーネントを使い続ける

⭕ 正しいアプローチ: npx shadcn migrateを実行してsonnerへの移行を完了させる

なぜ重要か: v4ではtoastコンポーネントがsonnerに置き換わっています。旧コンポーネントはメンテナンスされなくなり、バグ修正も提供されません。早期に移行するほどコストが低くなります。

失敗4: –diffを使わずにコンポーネントを上書き更新する

❌ よくある間違い: カスタマイズ済みのコンポーネントをそのままaddコマンドで上書き更新する

⭕ 正しいアプローチ: --diffフラグで差分を確認してから、手動でマージするか上書きを選ぶ

なぜ重要か: shadcn/uiのコンポーネントはプロジェクトにコピーして使うモデルです。更新時にカスタマイズが失われないよう、差分確認が必須です。

参考・出典

• March 2026 – shadcn/cli v4 — shadcn/ui公式（参照日: 2026-03-14）
• Skills – shadcn/ui — shadcn/ui公式ドキュメント（参照日: 2026-03-14）
• Tailwind v4 – shadcn/ui — shadcn/ui公式ドキュメント（参照日: 2026-03-14）
• Next.js 15 + React 19 – shadcn/ui — shadcn/ui公式ドキュメント（参照日: 2026-03-14）
• Releases · shadcn-ui/ui — GitHub公式リリースノート（参照日: 2026-03-14）

まとめ：今日から始める3つのアクション

1. 今日やること: 既存のshadcn/uiプロジェクトでnpx skills add shadcn/ui/shadcnを実行し、Claude CodeやCursorでのコード生成品質を体感する
2. 今週中: 新規プロジェクトをnpx shadcn@latest initでセットアップし、--dry-runと--diffフラグを使ったコンポーネント管理フローをチームに展開する
3. 今月中: 既存プロジェクトのTailwind v4移行（tailwind.config.js→globals.css @theme）とforwardRef削除codemodを適用し、React 19対応を完了させる

あわせて読みたい:

• AIエージェント構築完全ガイド — shadcn/uiで作るAIエージェントのUIパターン
• AIツール比較ガイド — Claude Code・Cursor・Windsurfの選び方と活用法

shadcn/uiを活用したAIアプリ開発・エージェントUI構築でお困りの方は、株式会社Uravationのお問い合わせフォームからお気軽にご相談ください。100社以上の企業向けAI導入支援の経験をもとにサポートします。

この記事はAIgent Lab編集部がお届けしました。