Tailwind CSS v4: 移行ガイドと新機能

Tailwind CSS v4 は、フレームワークの開始以来最も重要な書き換えです。 JavaScript 設定ファイルはなくなり、カスタム プロパティを使用した CSS ファーストの設定に置き換えられました。クラス API はほとんど変更されていませんが、内部構造は完全に新しくなっています。Rust ベースのエンジン (oxide)、P3 色域のファーストクラスのサポート、ネイティブ コンテナ クエリ、PostCSS プラグインではなく CSS と直接統合するビルド パイプラインです。

このガイドでは、変更内容、変更理由、実際の実運用アプリケーションを Tailwind v3 から v4 に移行する方法について説明します。ここでは、つまずくような重大な変更と、すぐに導入する価値のある新機能について説明します。

重要なポイント

• tailwind.config.js は非推奨です — 構成は @theme ディレクティブを使用して CSS に移行します
• インポートが @tailwind base/components/utilities から単一の @import "tailwindcss" に変更されました
• カスタム カラーは --color-* 名前空間の CSS カスタム プロパティを使用するようになりました
• content 構成は自動です — Tailwind v4 は glob 経由でファイルを自動的にスキャンします
• コンテナ クエリが @container および @sm:、@lg: バリアントで組み込まれるようになりました
• すべての組み込み色に対する oklch() 色空間を介した P3 色域サポート
• @apply は引き続き機能しますが、CSS カスタム プロパティでは必要性が低くなります
• JIT エンジンが Oxide (Rust) に置き換えられ、コンパイルが劇的に高速化

---

変更内容とその理由

Tailwind v3 は、処理パイプライン、JavaScript 構成ファイルとして PostCSS を使用し、JavaScript で記述された JIT エンジンを介してユーティリティ クラスを生成しました。これはうまく機能しましたが、制限がありました。

• 構成には JavaScript が必要であり、CSS のみのツールからはアクセスできません
• カスタム プロパティは Tailwind 構成とは別に設定する必要がありました
• コンテナクエリにはプラグインが必要です
• カラーシステムは P3 色域をサポートしていませんでした

Tailwind v4 は、構成を CSS 自体に移動し、ブラウザーのネイティブ CSS カスタム プロパティ システムを使用し、Rust でエンジンを書き換えて 5 ～ 10 倍高速なビルドを実現することで、これらすべてに対処します。

---

インストール

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

@tailwindcss/vite プラグインは Vite と直接統合されます。 Next.js (内部で PostCSS を使用する) の場合は、@tailwindcss/postcss を使用します。

---

CSS ファーストの構成

これが最大のコンセプト変更です。 globals.css は、Tailwind 構成の信頼できる情報源になります。

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

tailwind.config.js は削除できます (または、現時点では保持しておくこともできます。v4 は移行中に両方をサポートします)。

---

コンテンツの検出

Tailwind v4 はテンプレート ファイルを自動的に検出します。 v3 で細心の注意を払って維持していた content 構成は失われています。

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

v4 では、Tailwind は適切なデフォルトを使用してプロジェクトを自動的にスキャンします。通常とは異なる場所にファイルがある場合は、それらを明示的に含めることができます。

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

PostCSS 構成の更新

Next.js プロジェクト (および PostCSS ベースのセットアップ) の場合は、PostCSS 構成を更新します。

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

autoprefixer はデフォルトで @tailwindcss/postcss に含まれています。個別の autoprefixer 依存関係を削除します。

---

カラーシステム: OKLCH

Tailwind v4 は、組み込みのカラー パレットに OKLCH を使用します。 OKLCH は知覚的に均一な色空間であり、HSL とは異なり、人間の目には明度の調整が同じステップのように見えます。

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

より広い色域のディスプレイ (ほとんどの最新の携帯電話および Mac) の場合、OKLCH は sRGB では表現できない色を有効にします。 P3 をサポートしないディスプレイの場合、oklch() 値は自動的に rgb() に変換されます。

---

コンテナ クエリ — 組み込み

コンテナー クエリは v4 でファーストクラスになりました。プラグインは必要ありません:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

これにより、コンポーネント レベルの応答性が可能になります。サイドバー カードと全幅カードは、個別の CSS を使用しなくても異なるレイアウトを持つことができます。

名前付きコンテナを使用すると、特定の祖先をターゲットにできます。

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

CSS カスタム プロパティの統合

@theme で定義されたカスタム プロパティは、CSS、JavaScript、CSS 変数を読み取るデザイン ツールなど、どこからでもアクセスできます。

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

これにより、tailwind.config.js ファイルと tokens.ts ファイルで並列値を維持するパターンが置き換えられ、CSS に唯一の信頼できる情報源が存在します。

---

重大な変更

1.プラグイン API の変更

addBase、addComponents、addUtilities を使用する v3 プラグインは v4 と互換性がありません。新しいレイヤー システムを使用して CSS として書き換えます。

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply とカスタム クラス

非 Tailwind クラスの @apply は、v4 ではさらに制限されています。 @apply は実際のユーティリティ クラスでのみ使用してください。

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend はなくなりました

JS での構成はプライマリ パスではなくなりました。 CSS で @theme を使用します。両方がある場合は、CSS 設定が優先されます。

4.デフォルトのカラーパレットの名前

v4 ではいくつかの色の名前が変更されました。公式 codemod を実行してそれらをキャッチします。

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

移行戦略

大規模な実稼働アプリケーションの場合は、段階的に移行します。

フェーズ 1: アップデートのインストール

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

postcss.config.mjs を更新します。

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

globals.css を更新します。

/* Replace the three @tailwind directives */
@import "tailwindcss";

フェーズ 2: codemod を実行します

npx @tailwindcss/upgrade@next

これにより、色の名前の更新、設定の CSS への変換、手動での対応が必要な問題のフラグ付けなど、ほとんどの移行が自動化されます。

フェーズ 3: 構成を CSS に移動

tailwind.config.js テーマの値を取得し、CSS の @theme に移動します。確認後、設定ファイルを削除します。

フェーズ 4: 新機能の採用

必要に応じて、ビューポートベースの応答性ブレークポイントをコンテナー クエリに置き換えます。カスタム カラーに OKLCH を採用して、P3 色域のサポートを取得します。

---

パフォーマンスの向上

Tailwind v4 の Oxide エンジン (Rust) は、明らかに高速なビルドを実現します。

大規模なアプリケーションの場合、これにより、開発中の HMR が著しく高速になり、CI のビルド時間が大幅に短縮されます。

---

実際の移行例

以下は、デザイン システムの基本構成の実際の前後の例です。

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

CSS ネイティブの設定はより簡潔で、設定を読み取るための node_modules 依存関係が排除されます。

---

よくある質問

tailwind.config.js をすぐに削除する必要がありますか?

いいえ — Tailwind v4 は、移行中に JS 構成と CSS 構成の両方を同時にサポートします。 JS 構成は引き続き機能しますが、CSS の @theme などの機能は JS 構成なしでのみ使用できます。段階的に移行します。最初に v4 でアプリを構築し、次に徐々に設定を CSS に移行し、自信ができたら JS 設定を削除します。

既存の Tailwind v3 クラスは v4 でも動作しますか?

ユーティリティ クラスの大部分は変更されていません。一部の色の名前が更新され (一部のコンテキストではグレー→ニュートラル)、いくつかの非推奨のユーティリティが削除されました。 npx @tailwindcss/upgrade@next を実行すると、ほとんどの問題が自動的に検出されます。主な非互換性は、HTML/JSX でのクラスの使用方法ではなく、プラグインとカスタム テーマの設定にあります。

OKLCH はすべてのブラウザでサポートされていますか?

OKLCH は、すべての最新ブラウザ (Chrome 111 以降、Firefox 113 以降、Safari 15.4 以降) でサポートされています。 Tailwind v4 は、必要に応じて古いブラウザーのフォールバックを生成します。 P3 色域 (拡張色) のサポートには、広色域ディスプレイとサポートするブラウザーの両方が必要です。Tailwind は、より狭い色域ディスプレイ用に rgb() フォールバックを生成します。

Tailwind v4 を shadcn/ui で使用するにはどうすればよいですか?

shadcn/ui 2.0+ は Tailwind v4 をサポートします。 v4 CSS 変数形式を使用するように components.json を更新します。コンポーネント ライブラリは、テーマ設定に CSS カスタム プロパティを使用します。これは、Tailwind v4 の @theme システムに自然にマップされます。既存のプロジェクトで npx shadcn@latest init を実行して、v4 互換の構成を取得します。

新しい構成用の TypeScript タイプはありますか?

Tailwind v4 の構成は CSS であるため、構成自体に TypeScript タイプはありません。 IDE サポートは、カスタム プロパティを理解する CSS 言語サービスから提供されます。 TypeScript のテーマ値 (チャート、アニメーションなど) にアクセスするには、getComputedStyle を使用して実行時に CSS カスタム プロパティを読み取るか、ビルドの一部として CSS からトークン ファイルを生成します。

---

次のステップ

Tailwind CSS v4 は、新しいプロジェクトに採用し、既存のプロジェクトを計画する価値のある重要なアップグレードです。 ECOSIRE のフロントエンド スタックは、包括的な設計システムを備えた 249 ページの Next.js 16 アプリケーション全体で、実稼働環境で Tailwind CSS v4.1 を実行します。

Tailwind v4 の移行に関するサポートが必要ですか、それともゼロから構築された設計システムをご希望ですか? 弊社のフロントエンド エンジニアリング サービスをご覧ください して、弊社がどのようにお手伝いできるかをご確認ください。