React開発において、美しく機能的なUIコンポーネントを効率的に構築したいと考えていらっしゃいませんか。shadcn/uiは、従来のUIライブラリとは一線を画す革新的なアプローチで、開発者が真に求めていたUIソリューションを提供します。

本記事では、shadcn/uiの基本的なインストールから初期設定まで、初心者の方でも迷わず進められるよう、一歩ずつ丁寧に解説いたします。実際のコマンド実行例や設定ファイルの詳細も含めて、実践的な内容をお届けします。

shadcn/ui とは

shadcn/ui の概要

shadcn/uiは、Reactアプリケーション向けの再利用可能なコンポーネントコレクションです。特筆すべきは、従来のnpmパッケージとしてインストールする形式ではなく、コンポーネントのソースコードを直接プロジェクトにコピーする「Copy & Paste」アプローチを採用している点でしょう。

この設計により、開発者は完全にカスタマイズ可能なコンポーネントを手に入れることができます。

特徴とメリット

shadcn/uiの主な特徴をご紹介します。

特徴	説明	メリット
Copy & Paste方式	コンポーネントをソースコードとしてコピー	完全なカスタマイズが可能
Tailwind CSS ベース	スタイリングにTailwind CSSを使用	一貫性のあるデザインシステム
TypeScript サポート	完全なTypeScript対応	型安全性と開発体験の向上
Radix UI 基盤	アクセシビリティに優れたプリミティブ	高品質なUIコンポーネント
Zero Runtime	ランタイム依存がない	バンドルサイズの最適化

これらの特徴により、開発者は高品質なUIを迅速に構築できながら、必要に応じて詳細なカスタマイズも行えるのです。

他のUIライブラリとの違い

shadcn/uiと他の主要UIライブラリとの比較をご覧ください。

mermaidCopy codeflowchart TB
    traditional[従来のUIライブラリ] --> npm[npm install]
    npm --> blackbox[ブラックボックス化されたコンポーネント]
    blackbox --> limited[カスタマイズ制限]
    
    shadcn[shadcn/ui] --> copy[Copy & Paste]
    copy --> source[ソースコード所有]
    source --> freedom[完全なカスタマイズ自由度]

従来のライブラリでは、コンポーネントがパッケージとして提供されるため、内部実装を変更することが困難でした。一方、shadcn/uiでは、コンポーネントのソースコードが直接プロジェクトに追加されるため、必要に応じて自由に修正できます。

この違いにより、プロジェクト固有の要件に合わせた柔軟な対応が可能になるのです。

前提条件

shadcn/uiを導入する前に、以下の環境が整っていることをご確認ください。

Node.js環境

Node.js 16.8以降のバージョンが必要です。現在のバージョンを確認するには、以下のコマンドを実行してください。

javascriptCopy codenode --version

バージョンが古い場合は、Node.js公式サイトから最新版をインストールしましょう。

TypeScript知識レベル

shadcn/uiは完全にTypeScriptで構築されています。以下の知識があると、よりスムーズに進められます。

• 基本的なTypeScriptの型定義
• インターフェースの概念
• ジェネリクスの基礎理解

TypeScriptが初めての方でも、本記事の手順に従って進めることは可能です。

必要なツール

開発に必要なツールをご確認ください。

ツール	用途	推奨バージョン
Node.js	JavaScript実行環境	16.8+
Yarn	パッケージ管理	最新版
VS Code	エディタ	最新版
Git	バージョン管理	最新版

これらのツールが準備できましたら、次のステップに進みましょう。

インストール手順

Next.jsプロジェクトの準備

まず、新しいNext.jsプロジェクトを作成します。既存のプロジェクトがある場合は、このステップをスキップしてください。

javascriptCopy codeyarn create next-app my-shadcn-app --typescript --tailwind --eslint

作成されたプロジェクトディレクトリに移動します。

javascriptCopy codecd my-shadcn-app

プロジェクトが正常に作成されたことを確認するため、開発サーバーを起動してみましょう。

javascriptCopy codeyarn dev

ブラウザで http:​/​​/​localhost:3000 にアクセスし、Next.jsのデフォルトページが表示されれば成功です。

shadcn/ui CLIのインストール

shadcn/uiを管理するためのCLIツールをインストールします。このツールにより、コンポーネントの追加や設定が簡単に行えるようになります。

javascriptCopy codeyarn add -D shadcn-ui@latest

インストールが完了したら、CLIが正常に動作することを確認します。

javascriptCopy codenpx shadcn-ui --help

ヘルプメッセージが表示されれば、インストールは成功です。

初期設定コマンドの実行

shadcn/uiの初期設定を行います。このコマンドにより、プロジェクトに必要な設定ファイルが自動生成されます。

javascriptCopy codenpx shadcn-ui init

実行すると、いくつかの質問が表示されます。以下は推奨設定です。

textCopy codeWould you like to use TypeScript (recommended)? … yes
Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Where is your global CSS file? › app/globals.css
Would you like to use CSS variables for colors? … yes
Where is your tailwind.config.js located? › tailwind.config.js
Configure the import alias for components? › src/components
Configure the import alias for utils? › src/lib/utils

これらの設定により、プロジェクトに最適化された環境が構築されます。

基本設定

components.jsonの設定

初期化コマンドにより、components.json ファイルが生成されます。このファイルは、shadcn/uiの動作を制御する重要な設定ファイルです。

jsonCopy code{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

各項目の意味をご説明します。

• style: 使用するデザインスタイル（default/new-york）
• rsc: React Server Componentsの使用可否
• tsx: TypeScriptの使用設定
• tailwind: Tailwind CSSの設定情報
• aliases: インポートパスのエイリアス設定

この設定により、コンポーネントの生成場所やスタイルが決定されます。

Tailwind CSSの設定

shadcn/uiは、Tailwind CSSの設定に追加のカスタム設定が必要です。tailwind.config.jsを確認してみましょう。

javascriptCopy codeconst { fontFamily } = require("tailwindcss/defaultTheme")

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: [
    './pages/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
    './src/**/*.{ts,tsx}',
  ],
  theme: {
    container: {
      center: true,
      padding: "2rem",
      screens: {
        "2xl": "1400px",
      },
    },
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        secondary: {
          DEFAULT: "hsl(var(--secondary))",
          foreground: "hsl(var(--secondary-foreground))",
        },
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      fontFamily: {
        sans: ["var(--font-sans)", ...fontFamily.sans],
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

この設定により、CSS変数を使用したテーマシステムと、アニメーション機能が利用できるようになります。

TypeScriptの型設定

shadcn/uiのコンポーネントを正しく動作させるため、TypeScriptの設定も確認します。tsconfig.jsonにパスエイリアスが正しく設定されているか確認しましょう。

jsonCopy code{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

この設定により、@​/​componentsや@​/​lib​/​utilsといったエイリアスを使用してインポートできるようになります。

初回コンポーネント導入

コンポーネントの追加方法

それでは、実際にshadcn/uiのコンポーネントを追加してみましょう。最初の例として、Buttonコンポーネントを導入します。

javascriptCopy codenpx shadcn-ui add button

このコマンドを実行すると、以下のファイルが自動生成されます。

• src​/​components​/​ui​/​button.tsx
• 必要な依存関係の自動インストール
• 関連するユーティリティ関数

生成されたButtonコンポーネントを確認してみましょう。

mermaidCopy codeflowchart LR
    cli[shadcn-ui CLI] -->|add button| generate[コンポーネント生成]
    generate --> button[button.tsx]
    generate --> utils[utils関数]
    generate --> deps[依存関係インストール]
    button --> ready[使用準備完了]

CLIコマンド一つで、使用準備が整ったコンポーネントが手に入ります。

基本的な使用例

生成されたButtonコンポーネントを実際に使用してみましょう。app​/​page.tsxを編集します。

typescriptCopy codeimport { Button } from "@/components/ui/button"

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <div className="space-y-4">
        <h1 className="text-4xl font-bold">shadcn/ui テスト</h1>
        <div className="flex gap-4">
          <Button>デフォルトボタン</Button>
          <Button variant="secondary">セカンダリ</Button>
          <Button variant="outline">アウトライン</Button>
        </div>
      </div>
    </main>
  )
}

このコードにより、異なるバリアントのボタンが表示されます。各ボタンは、Tailwind CSSクラスによってスタイリングされており、レスポンシブ対応も自動的に行われます。

カスタマイズ方法

shadcn/uiの最大の利点は、コンポーネントを自由にカスタマイズできることです。生成されたButtonコンポーネントを確認してみましょう。

typescriptCopy codeimport * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

この設定ファイルを編集することで、新しいバリアントやサイズを追加できます。例えば、新しいバリアントを追加する場合は、以下のように記述します。

typescriptCopy codevariant: {
  // 既存のバリアント...
  custom: "bg-purple-600 text-white hover:bg-purple-700",
}

コンポーネントのソースコードを直接編集できるため、プロジェクトの要件に完全に合致したUIを作成できるのです。

動作確認

サンプルページの作成

インストールと設定が正しく完了したかを確認するため、より複雑なサンプルページを作成してみましょう。複数のコンポーネントを追加します。

javascriptCopy codenpx shadcn-ui add card input label

これらのコンポーネントを使用したサンプルページを作成します。

typescriptCopy codeimport { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export default function Home() {
  return (
    <main className="container mx-auto py-12">
      <div className="max-w-md mx-auto">
        <Card>
          <CardHeader>
            <CardTitle>ログインフォーム</CardTitle>
          </CardHeader>
          <CardContent className="space-y-4">
            <div className="space-y-2">
              <Label htmlFor="email">メールアドレス</Label>
              <Input 
                id="email" 
                type="email" 
                placeholder="example@domain.com" 
              />
            </div>
            <div className="space-y-2">
              <Label htmlFor="password">パスワード</Label>
              <Input 
                id="password" 
                type="password" 
                placeholder="パスワードを入力" 
              />
            </div>
            <Button className="w-full">ログイン</Button>
          </CardContent>
        </Card>
      </div>
    </main>
  )
}

このサンプルコードでは、Card、Input、Label、Buttonの各コンポーネントが連携してログインフォームを構成しています。

動作テスト

開発サーバーを起動して、作成したサンプルページの動作を確認します。

javascriptCopy codeyarn dev

ブラウザで以下の項目をチェックしてください。

1. スタイリングの確認: コンポーネントが期待通りのデザインで表示されているか
2. インタラクションの確認: ボタンのホバー効果や入力フィールドのフォーカス状態
3. レスポンシブ対応: 画面サイズを変更した際の表示
4. アクセシビリティ: キーボードナビゲーションやスクリーンリーダー対応

これらが正常に動作していれば、インストールと設定は成功です。

トラブルシューティング

よくある問題と解決方法をご紹介します。

CSS変数が反映されない場合

app​/​globals.cssにshadcn/uiの基本スタイルが含まれているか確認してください。

cssCopy code@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* その他のCSS変数... */
  }
}

コンポーネントのインポートエラー

TypeScriptのパスエイリアスが正しく設定されているか、tsconfig.jsonを確認してください。

jsonCopy code{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

型エラーが発生する場合

必要な型定義パッケージがインストールされているか確認します。

javascriptCopy codeyarn add -D @types/node @types/react @types/react-dom

これらの対処法により、ほとんどの初期設定問題は解決できるでしょう。

まとめ

shadcn/uiのインストールと初期設定について、一連の手順をご説明いたしました。重要なポイントを振り返ってみましょう。

shadcn/uiの導入により、以下のメリットを得ることができます。

• 高品質なUIコンポーネント: アクセシビリティとデザイン性を両立
• 完全なカスタマイズ性: ソースコードを直接編集可能
• 優れた開発体験: TypeScriptとTailwind CSSによる型安全性
• 効率的な開発: CLIツールによる簡単なコンポーネント管理

本記事で紹介した手順に従うことで、初心者の方でも確実にshadcn/uiを導入できるはずです。次のステップとしては、より多くのコンポーネントを試し、実際のプロジェクトに適用してみることをお勧めします。

shadcn/uiを活用して、素晴らしいUIを構築していきましょう。

関連リンク

• shadcn/ui公式サイト
• Radix UI ドキュメント
• Tailwind CSS 公式ドキュメント
• Next.js 公式ドキュメント
• TypeScript ハンドブック