Tailwind v4 + Vite：5 分で完成する設定テンプレートとディレクトリ構成

去年、新しいプロジェクトで Tailwind を設定したとき、30 分かけてもまだ tailwind.config.js の content パスをいじっていました。そのとき思ったんです。「これ、もっと簡単にならないの？」と。

そして今年、Tailwind v4 が本当にそれを実現しました。

いまや 3 行のコードだけで完全な Tailwind プロジェクトを動かせます——PostCSS の設定も、tailwind.config.js も、どのファイルをスキャンするか手動で指定する必要すらありません。正直、この変化を初めて見たときは、ちょっと信じられませんでした。

この記事は、その 30 分の手間をまるごと省くためのものです。完全なテンプレートに加えて、半年使ってみてなかなか使いやすいと感じたディレクトリ構成も紹介します。

1. なぜ Tailwind v4 + Vite を選ぶのか？

1.1 v4 は本当にそんなに速いのか？

公式はビルド速度が 10 倍向上したと言っています。実際に測ってみると、中小規模のプロジェクトで 8 秒が 1 秒未満になりました。この向上の主因は新しい Oxide エンジン——Rust で書かれている、と言えばもう説明はいらないでしょう。

でも、もっとうれしかったのは設定の簡略化です。以前は Tailwind プロジェクトを新規作成するたびに、tailwind.config.js、postcss.config.js、Vite の設定、さらに CSS ファイルの @tailwind ディレクティブと、3〜4 個のファイルをいじる必要がありました。いまは？1 つのファイルを直すだけで済みます。

1.2 Vite の速さは伊達じゃない

Vite の開発サーバーはほぼ一瞬で起動します。ホットリロード（HMR）も非常に速く、CSS を直してページを更新しても遅延はほとんど感じません。日々の開発体験の向上という点で、正直、一度使うと戻れません。

1.3 v3 vs v4：ひと目でわかる比較

まずはこの表を見てください：

わかりますか？v4 の核心的な発想は、設定を JS から CSS へ移したことです。これは何を意味するのか？スタイルを書きながらついでに設定も変えられて、2 つのファイルを行ったり来たりしなくて済むということです。

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

2. 5 分で完成する設定テンプレート

準備はいいですか？さっそく始めましょう。

2.1 プロジェクトの初期化

ターミナルを開いて、次の数行を実行します：

# TypeScript テンプレートで新しい Vite プロジェクトを作成
npm create vite@latest my-project -- --template vanilla-ts

# プロジェクトディレクトリへ移動
cd my-project

# 依存関係をインストール
npm install

この手順はおよそ 30 秒です。

2.2 Tailwind v4 のインストール

# Tailwind CSS と公式 Vite プラグインをインストール
npm install tailwindcss @tailwindcss/vite

この 1 行だけです。postcss も autoprefixer も不要、v4 にすでに内蔵されているからです。

2.3 Vite の設定

vite.config.ts を開いて、こう書き換えます：

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  // Tailwind プラグインを追加するだけ
  plugins: [tailwindcss()],
})

3 行のコード。本当にこれだけシンプルです。

2.4 CSS ファイルの作成

src/styles/ の下に main.css を作成します：

/* src/styles/main.css */

/* Tailwind を読み込む — この 1 行で基本スタイルがすべて整う */
@import "tailwindcss";

/* テーマのカスタマイズ（任意）*/
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
}

ここの @theme ブロックが v4 の新構文です。この中に色・フォント・余白などを CSS 変数の形で定義できます。以前 tailwind.config.js を書いていたころより、ずっと直感的です。

2.5 CSS の読み込み

src/main.ts を開いて、いちばん上に 1 行追加します：

// src/main.ts
import './styles/main.css'

// もともとのコード...

2.6 動作確認

index.html か何かのページコンポーネントで試してみます：

<div class="bg-primary text-white p-4 rounded-lg">
  Tailwind v4 が動きました！
</div>

そして実行します：

npm run dev

ブラウザを開いて、青い背景のカードが見えたら設定成功です。時間を計ってみましたが、本当に 5 分以内に動かせます。

3. 推奨のディレクトリ構成

プロジェクトが動き出したら、ファイルを次のように整理することをおすすめします：

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

3.1 完全なディレクトリ構成

my-project/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # 基本 UI コンポーネント
│   │   │   ├── Button.ts
│   │   │   └── Input.ts
│   │   └── layout/           # レイアウトコンポーネント
│   │       ├── Header.ts
│   │       └── Footer.ts
│   ├── styles/
│   │   ├── main.css         # メインエントリー（Tailwind を読み込む）
│   │   ├── components.css   # コンポーネント関連のスタイル
│   │   └── utilities.css    # カスタムユーティリティクラス
│   ├── utils/
│   │   └── helpers.ts
│   ├── pages/               # ページファイル（マルチページアプリの場合）
│   ├── assets/              # 静的リソース
│   │   ├── images/
│   │   └── fonts/
│   ├── main.ts
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

3.2 なぜこう分けるのか？

components/ui/ には基本コンポーネント——ボタン、入力欄、モーダルなど——を置きます。再利用性が高く、具体的なビジネスロジックに依存しないものです。

components/layout/ にはレイアウトコンポーネント——Header、Footer、Sidebar——を置きます。これらはページの骨格を担い、ui コンポーネントとは位置づけが少し異なります。

styles/ には CSS を独立して置きます。Tailwind v4 以降は、設定がすべて CSS 内にあるので、スタイルをまとめて管理するのが好みになりました。一カ所にまとめると修正もラクです。

utils/ にはユーティリティ関数を置きます。日付のフォーマットや文字列処理のような純粋関数です。

3.3 CSS ファイルの整理の仕方

/* src/styles/main.css — エントリーファイル */

/* Tailwind を読み込む */
@import "tailwindcss";

/* ほかのスタイルファイルを読み込む */
@import "./components.css";
@import "./utilities.css";

/* グローバルな基本スタイル */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }

  /* リンクのデフォルトスタイル */
  a {
    @apply text-primary hover:underline;
  }
}

@layer base は Tailwind のレイヤー機構で、最も下層のスタイルを定義するのに使います。直接 body { ... } と書くより優れている点は、Tailwind が優先度の問題をきちんと処理してくれることです。

4. v3 移行チェックリスト

手元に v3 のプロジェクトがあってアップグレードしたいなら、このチェックリストどおりに進めればいいです。先日いくつかのプロジェクトをアップグレードしたので、踏んだ落とし穴も書き出しておきました。

4.1 設定ファイルの移行

• tailwind.config.js を削除（Tailwind の設定しかない場合）
• postcss.config.js を削除（Tailwind 用にしか使っていない場合）
• CSS ファイルに @import "tailwindcss" を 1 行追加
• vite.config.ts を更新し、@tailwindcss/vite プラグインに置き換え

4.2 依存関係の更新

# 旧依存関係をアンインストール
npm uninstall postcss autoprefixer tailwindcss

# 新依存関係をインストール
npm install tailwindcss @tailwindcss/vite

• アンインストールコマンドを実行
• インストールコマンドを実行
• package.json でバージョン番号を確認

4.3 スタイルの調整

• @tailwind base; @tailwind components; @tailwind utilities; を @import "tailwindcss"; に置き換え
• tailwind.config.js のテーマ設定を CSS の @theme ブロックへ移行
• カスタムユーティリティクラスが正常に動くか確認

テーマ設定の移行例：

/* v3 の tailwind.config.js */
module.exports = {
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

/* v4 の main.css */
@theme {
  --color-primary: #3b82f6;
}

4.4 テストと検証

• npm run dev で開発環境が正常か確認
• npm run build で本番ビルドが成功するか確認
• ページを開いてスタイルが欠けていないか確認
• CSS ファイルを直して、ホットリロードが動くか確認

5. よくある問題と解決策

アップグレードや設定の過程で、いちばん多く遭遇した問題はこの数つです。

5.1 スタイルが反映されない

class="bg-primary" と書いたのに、ページが真っ白。どういうこと？

調査手順：

1. ブラウザの開発者ツールを開き、CSS ファイルが正常に読み込まれているか見る
2. main.ts で本当に CSS ファイルを読み込んでいるか確認
3. vite.config.ts のプラグイン設定が正しいか確認

一度、main.ts で import './styles/main.css' を書き忘れていたことがありました。とても初歩的なミスですが、確かに見落としやすいです。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

5.2 ホットリロードが動かない

CSS を直したのに、ページがピクリとも動かない。

調査手順：

1. Vite のバージョンが >= 5.0 か確認（古いバージョンには互換性問題あり）
2. 開発サーバーを再起動してみる
3. ブラウザキャッシュをクリアするか、シークレットウィンドウを開く

それでもダメなら、コンソールにエラーが出ていないか確認します。ほかのプラグインとの競合が原因のこともあります。

5.3 ビルド後の CSS サイズが大きすぎる

本番環境でビルドすると、CSS ファイルが数百 KB に膨らむ。

調査手順：

1. 使っているのが v4 の新版か確認（旧版は tree-shaking が十分にクリーンではない）
2. アイコンライブラリ全体やほかの大型依存を取り込んでいないか確認
3. @layer でスタイルをレイヤー分けすると、Tailwind が優先度や重複の処理をうまくやってくれる

正直、たいていの場合 v4 の出力はすでにかなりコンパクトです。それでも大きすぎるなら、おそらく自分が CSS に書きすぎているのが原因でしょう。

まとめ

いろいろ話しましたが、核心はこの数つだけです：

1. インストール：npm install tailwindcss @tailwindcss/vite
2. Vite の設定：tailwindcss() プラグインを 1 つ追加
3. CSS を書く：@import "tailwindcss" + @theme でテーマ設定
4. 動かす：npm run dev

v4 が v3 に対して最大の変化は、設定を JS から CSS へ移したことです。最初は少し慣れないかもしれませんが、しばらく使うとこのほうが直感的だと気づきました——スタイルを直すついでに設定も変えられて、ファイル間を行き来しなくて済むのです。

v3 から移行してきたなら、tailwind.config.js のテーマ設定を CSS の @theme 構文へ書き換えるのを忘れないでください。少し手間はかかりますが、得られるのはより速いビルド速度とよりシンプルなプロジェクト構成です。どう計算しても割に合う取引です。