Tailwind CSS v4 を導入する手順

この記事は Tailwind v4 前提です。
v3との違いに詰まったのでまとめます。

0. 前提

• Node.js 18 以上を推奨（20 系が安定）
• 新規プロジェクト例は Vite + React を利用

# プロジェクト作成
npm create vite@latest my-app -- --template react
cd my-app

# 依存追加
npm install

---

1. Tailwind v4 をインストール

npm i -D tailwindcss

v4 は 設定ファイルなし で動きます。tailwind.config.js は不要です。

---

2. CSS に 1 行だけ書く

src/index.css を開き、先頭に これだけ 追記（または置き換え）します。

@import "tailwindcss";

旧来の @tailwind base; @tailwind components; @tailwind utilities; ではありません。
v4 の 正解は @import "tailwindcss"; です。

Vite プロジェクトであれば、特別な設定なしで取り込まれます（src/main.jsx で import './index.css' がある前提）。

---

3. 動作確認

src/App.jsx を仮で書き換えて、Tailwind のクラスが効くか確認します。

export default function App() {
  return (
    <div className="min-h-screen grid place-items-center bg-[#F9FAFB] text-[#2B3541]">
      <div className="max-w-[440px] w-full mx-auto px-4 py-8">
        <h1 className="text-2xl font-bold text-center mb-6">Hello Tailwind v4</h1>

        <button
          className="
            rounded-xl border-2 border-[#2B3541]
            px-6 py-3 text-lg font-medium
            bg-white text-[#2B3541]
            shadow-[0_5px_0_#2B3541]
            transition-all duration-150
            active:translate-y-[5px] active:shadow-none
          "
        >
          ボタンのサンプル
        </button>
      </div>
    </div>
  );
}

起動：

npm run dev

画面が表示され、ボタンの押し込みアニメーションや色が効いていれば成功です。

---

4. よくあるハマりどころ（v4 版）

4.1 開発サーバーを再起動する

新しくパッケージを入れた直後に スタイルが効かない ときは、Vite の dev サーバーを一度止めて再起動してください。

4.2 CSS を正しく読み込む

src/main.jsx に import './index.css' がないと反映されません。Vite テンプレートでは最初から入っています。

4.3 ダークモードを使わない場合

v4 はダークモードの前提設定も不要です。クラスに dark: を使わなければ何も起きないので、何もしなくてOK です。

4.4 動的クラスの扱い

テンプレート文字列でクラス名を組み立てると最適化から漏れる場合があります。
例えば bg-${color} などは避け、使う可能性のあるクラスをそのまま文字列で書く か、clsx などで条件分岐してください。

// 悪い例（動的に bg- を合成）
<div className={`bg-${color} text-white`}>...</div>

// 良い例（条件分岐で明示）
<div className={isPrimary ? "bg-[#00A8A5]" : "bg-gray-200"}>...</div>

4.5 v3 からの移行で混在させない

@tailwind base など 旧記法と混在 させると崩れます。@import "tailwindcss"; へ一本化しましょう。
tailwind.config.js や postcss.config.js は基本的に不要です。プラグインや独自プリセットが必要になったら検討します。

---

5. プロダクションビルド

npm run build
npm run preview   # ローカルでビルド結果を確認

v4 は不要なユーティリティを自動で取り除くため、追加の purge 設定は不要 です。

6. レイアウトと共通 UI の小ワザ

6.1 スマホ中心の横幅

「スマホで読みやすい」幅の目安として max-w-[440px] は扱いやすいです。

<div className="max-w-[440px] w-full mx-auto px-4">
  {/* コンテンツ */}
</div>

6.2 押し込みボタン（共通コンポーネント）

export default function Button({ className = "", children, ...props }) {
  const base = [
    "inline-flex items-center justify-center select-none",
    "rounded-xl border-2 border-[#2B3541]",
    "px-6 py-3 text-lg",
    "shadow-[0_5px_0_#2B3541]",
    "transition-all duration-150",
    "active:translate-y-[5px] active:shadow-none",
    "cursor-pointer disabled:cursor-not-allowed disabled:opacity-50",
  ].join(" ");

  return (
    <button className={`${base} ${className}`} {...props}>
      {children}
    </button>
  );
}

7. 追加カスタマイズが必要になったら

• 独自カラーやフォントスケールを大量に使う
• プラグインを追加したい（フォーム、typography など）

といった場合は、最小構成から 段階的に 設定ファイル導入を検討します。まずは v4 の「設定なしで始める」流儀に乗って、必要になったら拡張するのが安全です。

8. まとめ

• v4 は @import "tailwindcss"; の 1 行でスタートできる
• Vite + React なら追加設定なしで動作
• ダークモード等は使わなければ何もしないでOK
• 動的クラスは 条件分岐で明示 するのがコツ
• 設定ファイルは「必要になってから」追加で十分