Tailwind CSS v4 セットアップ完全ガイド｜Vite + @theme

Tailwind CSS v4 のセットアップを Vite で実際に走らせ、ビルド出力と @theme のカスタムトークンまで確認しました。tailwind.config.js が不要になった理由と、v3 からの移行で書き換える箇所を実測つきでまとめます。

Tailwind CSS v4 がリリースされてだいぶ経ちましたね。v3 から大幅に仕組みが変わっていて、「まだ v3 のまま」「設定方法がわからない」という人も多いんじゃないでしょうか。

今回は、Tailwind CSS v4 のセットアップ手順を Vite と合わせて完全解説します。CSSファースト設定や高速な Oxide エンジンなど、v4 の注目ポイントも押さえていきますよ。

この記事が解決する悩み

• v4に上げたら設定の書き方が変わって、何をどこに書くのか分からない
• Viteと組み合わせたときのセットアップ手順を知りたい

対象読者: Tailwind CSSでフロントエンドを組んでいる人
前提知識: Tailwind v3を触ったことがあること

結論：v4 はここが変わった

まず、v4 の主要な変更点をざっくりまとめますね。

• CSSファースト設定：tailwind.config.js はもう不要。CSS に直接 @theme で書く
• Rust 製 Oxide エンジン：ビルドが超高速。公式の v4.0 リリース告知では、フルビルドが最大 5 倍・インクリメンタルビルドが 100 倍以上と報告されています
• 自動ツリーシェイク：使ってないユーティリティは自動で除外。Purge 設定不要
• @import "tailwindcss" 一本化：@tailwind base/components/utilities は廃止
• OKLCH 色空間：デフォルトのカラー値が OKLCH に。人間の知覚に合った色設計

「え、config.js いらないの？」って思うかもしれませんが、本当に要らないんです。CSS だけで完結するようになりました。

v3 と v4 の違い

先に v3 と v4 の違いを表で並べておきます。設定の置き場所がまるごと変わったのが分かるはずです。

Vite プロジェクトに Tailwind CSS v4 をセットアップする

では実際に手を動かしてセットアップしていきましょう。

1. プロジェクトを作成

まずは Vite プロジェクトを作ります。お好みのテンプレートで OK です。Vite 側のバージョンも上げる予定なら、先にVite 8 移行ガイドで壊れる設定を確認しておくと安全です。

$ npm create vite@latest my-app -- --template vanilla
npm warn exec The following package was not found and will be installed: create-vite@9.2.1

◇  Scaffolding project in my-app...
└  Done. Now run:

  cd my-app
  npm install
  npm run dev

React や Vue を使うなら --template react-ts でも大丈夫です。

2. tailwindcss と Vite プラグインをインストール

Tailwind CSS v4 と Vite プラグインをインストールします。

$ npm install --save-dev tailwindcss @tailwindcss/vite
added 17 packages, and audited 33 packages in 3s

11 packages are looking for funding
found 0 vulnerabilities

これだけで OK。tailwindcss 本体と、Vite 用プラグインが入ります。余計な設定ファイルは一切不要です。

3. Vite 設定にプラグインを追加

vite.config.js を開いて、Tailwind プラグインを追加します。

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

これだけ。v3 のように PostCSS 経由じゃなくて、Vite プラグインとして直接動くんです。

4. CSS にエントリポイントを追加

メインの CSS ファイル（src/style.css）の先頭にこれを書きます。

@import "tailwindcss";

@tailwind base や @tailwind utilities はもう書きません。これ一本で全部読み込まれます。

5. HTML で Tailwind クラスを使う

あとは普通にクラスを書くだけです。

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
  </head>
  <body class="bg-slate-100 min-h-screen flex items-center justify-center">
    <div class="bg-white p-8 rounded-2xl shadow-lg">
      <h1 class="text-3xl font-bold text-brand">Hello Tailwind v4!</h1>
      <p class="mt-4 text-slate-600 font-heading">Vite プラグイン経由で読み込んでいます。</p>
    </div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

6. ビルドして確認

$ npx vite build
vite v8.3.0 building client environment for production...
transforming...
✓ 5 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                 0.67 kB │ gzip: 0.47 kB
dist/assets/index-wBUcFaIT.css  8.74 kB │ gzip: 2.39 kB
dist/assets/index-CbZYlJtI.js   0.67 kB │ gzip: 0.38 kB

✓ built in 177ms

これで dist/ 以下にビルド成果物が出力されます。たったこれだけで Tailwind が使えるようになりました。

カスタムデザイントークンを定義する（@theme）

ここが v4 の一番大きな変更点ですね。

v3 までは tailwind.config.js の theme.extend で色やフォントを定義していましたが、v4 では CSS に @theme ディレクティブを書きます。

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.21 259.82);
  --color-brand-dark: oklch(0.49 0.24 264.38);
  --font-heading: "Inter", sans-serif;
}

/* 出力CSS（抜粋） */
--color-brand:oklch(62% .21 259.82)

これだけで text-brand、bg-brand-dark、font-heading といったクラスが使えるようになります。

ポイントは変数名のルールですね：

• 色：--color-* → text-* / bg-* / border-* など
• フォント：--font-* → font-*
• スペーシング：--spacing-* → p-* / m-* など
• 角丸：--radius-* → rounded-*
• 影：--shadow-* → shadow-*
• ブレークポイント：--breakpoint-* → sm:* / md:* など

慣れるとむしろ直感的ですね。CSS 変数としてもそのまま使えるので、var(--color-brand) みたいな参照ももちろん可能です。

v3 からの移行ポイント

既存の v3 プロジェクトを v4 に上げる場合、注意する点をまとめます。

公式 Codemod を使う

いきなり手作業で書き換えるのは大変なので、公式のアップグレードツールを使いましょう。

$ npx @tailwindcss/upgrade
≈ tailwindcss v4.3.3
│ ↳ Upgrading from Tailwind CSS `v3.4.19`
│ ↳ Linked `.\tailwind.config.js` to `.\src.css`
│ ↳ Migrated configuration file: `.\tailwind.config.js`
│ ↳ Migrated stylesheet: `.\src.css`
│ ↳ Updated package: `tailwindcss`
│ ↳ Migrated templates for configuration file: `.\tailwind.config.js` (0 files changed)
│ ↳ No PostCSS config found, skipping migration.

v3.4.19 のプロジェクトで実際に走らせたところ、tailwind.config.js は @theme に変換されたうえで削除され、CSS は @import "tailwindcss"; に書き換わりました。

ただし devDependencies に残る postcss と autoprefixer は自動では外れません。v4 はどちらも内蔵しているので、手で消しておきましょう。

/* 変換後の src.css（抜粋） */
@import "tailwindcss";

@theme {
  --color-brand: #2f6fed;
}

/* 互換用に自動で足される（border の既定色が currentcolor に変わったため） */
@layer base {
  *, ::after, ::before, ::backdrop, ::file-selector-button {
    border-color: var(--color-gray-200, currentcolor);
  }
}

自分で確認するポイント

• @tailwind base/components/utilities を削除：@import "tailwindcss" に一本化
• tailwind.config.js を削除：設定は CSS の @theme に移行
• postcss.config.js を見直し：Vite を使うなら @tailwindcss/vite プラグインに切り替え
• darkMode 設定は不要に：v4 はデフォルトで media ベースのダークモード。セレクタ方式にしたいなら @custom-variant dark (&:where(.dark, .dark *)); を CSS に書く
• プラグインの対応状況を確認：v3 用のプラグイン（@tailwindcss/forms など）は v4 に対応したものを入れ直す

Vite 以外のセットアップ方法

今回は Vite を推奨しましたが、他にも方法はあります。

PostCSS（Next.js など）

$ npm install --save-dev tailwindcss @tailwindcss/postcss

postcss.config.js にこう書きます。

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

CLI（ビルドツール非依存）

$ npm install --save-dev tailwindcss @tailwindcss/cli
$ npx @tailwindcss/cli -i src/style.css -o dist/style.css --watch

シンプルな静的サイトならこれで十分です。

よくあるトラブルと対処法

tailwindcss のクラスが効かない

いちばん多いのが、v3 の @tailwind base; が残っているパターンです。v4 はこのディレクティブを黙って無視するので、エラーも警告も出ません。

実測ではビルドが 75ms で成功し、出力 CSS は 2.04 kB（@layer properties のみ）で bg-slate-100 のようなユーティリティは1つも入りませんでした。CSS の先頭を @import "tailwindcss"; に置き換えれば直ります。

tailwind.config.js に書いた設定が効かない

v4 は tailwind.config.js を読みません。実測では config に legacy という色を足しても、出力 CSS には現れませんでした。

設定は CSS の @theme に移してください。移行は前述の公式 codemod が変換してくれます。

Vite の HMR が反応しない

@tailwindcss/vite の peerDependencies は vite ^5.2.0 || ^6 || ^7 || ^8 です（4.3.3 の package.json で確認）。これより古い Vite だとプラグインが読み込まれません。

@theme で定義した色が出力 CSS に出ない

v4 は使われていないトークンを出力しません。実測では text-brand で使った --color-brand は出力され、定義しただけの --color-unused は出力 CSS に含まれませんでした。

定義しただけでは入らないので、必ずクラスとして使ってください。

【広告】独自ドメインを取得してWebサービスを公開するならお名前.comがおすすめです。格安で .com ドメインが取得できます。

まとめ

Tailwind CSS v4 は、セットアップが格段にシンプルになりました。特に CSS ファースト設定への移行は「設定ファイルを探し回る」ストレスから解放してくれますね。

• インストールは npm install --save-dev tailwindcss @tailwindcss/vite だけ
• 設定は CSS の @theme に集約
• ビルドは Oxide エンジンで爆速
• 不要なクラスは自動で除外

まだ v3 のままの人は、この機会にぜひ v4 に移行してみてください。体感できるレベルの高速さと、設定のシンプルさを実感できると思いますよ。

検証環境

上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

参考

本文の記述は以下の一次情報を確認して書いています。

• Tailwind CSS v4 + Vite セットアップ（公式）
• Tailwind CSS v4.0 リリース告知（公式ブログ）
• テーマ変数 @theme（公式ドキュメント）
• v3→v4 アップグレードガイド / @tailwindcss/upgrade（公式）

あわせて読みたい

• 【pnpm】ERR_PNPM_IGNORED_BUILDS の直し方 — allowBuilds へ移行
• 【Node.js】ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX の直し方
• 【Node.js】Node 26 完全ガイド2026 — Temporal API と Iterator.concat
• 【Vite】Vite 8 移行ガイド2026 — Rolldown 統合で壊れる設定

【広告】このサイトはConoHa WINGで運営しています。高速で安定した運営ができています。いつもありがとう！！