Tailwind CSS v4に移行したら設定ファイルが消えた話！移行で見た目が変わるポイントも

🙌 結論から

Tailwind CSS v4 に移行してみたところ、tailwind.config.js が完全に不要になり、CSS ファイルだけで設定が完結するようになりました！

これまで tailwind.config.js の theme.extend に色・フォント・スペーシングを書いていたものが、全部 CSS の @theme ディレクティブに移行できます。

移行ツールの @tailwindcss/upgrade を使えば既存プロジェクトもほぼ自動で対応できたので、思ったよりハードルは低かったです(^_^)

新規プロジェクトなら最初から v4 で始めた方がいいです！

💡 Tailwind CSS v4 で何が変わったか

最も大きな変化は、設定が CSS ファースト になったことですかね。

v3 までは tailwind.config.js に JavaScript で書くのが当たり前でしたが、v4 では CSS の @theme ディレクティブでカスタムデザイントークンを直接定義できます。

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --spacing-18: 4.5rem;
}

これだけで bg-brand や font-sans、p-18 といったクラスが自動生成されます！

また、パフォーマンス面でも改善が入っていて、CSS の生成速度がかなり速くなっています。

CSS 変数（カスタムプロパティ）との統合も自然で、:root で定義したトークンを Tailwind クラスとして使える仕組みもあります。設計の一貫性が保ちやすくなった点が個人的には相当ありがたいです。

👀 実際に移行してみた

移行には公式が提供している @tailwindcss/upgrade を使いました。

npx @tailwindcss/upgrade

実行すると、tailwind.config.js の設定を @theme ディレクティブに変換してくれます。

私のプロジェクトでは色・フォント・ブレークポイントのカスタムトークン程度だったので、ほぼ自動変換で済みました。

ただ、カスタムプラグインを使っていた部分は自動変換の対象外で、手動での書き換えが必要でしたが(・_・;)

プラグインの数が多いプロジェクトは移行コストが高くなるかもしれないので、移行前に一度プラグイン一覧を確認しておくといいと思います。

移行後に tailwind.config.js が消えたときは少し不安でしたが、CSS ファイルだけで設定が見渡せるのは想像以上に快適でした。

😎 使ってみた感想

実際に使ってみて一番よかったのは、プロジェクトルートがスッキリしたことですね。

v3 では tailwind.config.js の theme.extend が肥大化していたのですが、CSS に移すことで「どこに何が書いてあるか」が直感的にわかるようになりました。

IDE でカーソルを当てたときに CSS 変数として値がわかるのも意外と便利で、チームでのコードレビューがしやすくなりました！

一方で、移行は一度やってしまえば快適なのですが、既存プロジェクトへの適用は慎重に進める必要があります。

CI で動作確認をしっかりしながら進めれば問題ありませんが、移行前に変更点のリリースノートを読んでおくことをおすすめします(｀・ω・´)

🎨 @utilityディレクティブで独自ユーティリティを作った

@theme でデザイントークンを定義するのに慣れてきたところで、独自のユーティリティクラスを作る場面にも遭遇しました。

v3では tailwind.config.js の plugin() 関数を使っていた部分が、v4では @utility ディレクティブでCSSファイル内に直接書けるようになっています。

@utility scrollbar-hidden {
  &::-webkit-scrollbar {
    display: none;
  }
  scrollbar-width: none;
}

これで class="scrollbar-hidden" がそのまま使えるようになります。JavaScriptの設定ファイルを開かずに、CSSを触っているときの流れのまま独自クラスを追加できるのがかなり快適でした(・∀・)

もう一つ体感したのが、ビルドそのものの速さです。

v4の核になっている Oxide エンジンはRustでフルスクラッチされていて、CSS解析部分には Lightning CSS（同じくRust製）が使われています。

私のプロジェクト規模だと極端な差は感じにくかったんですが、公式のベンチマークではフルビルドで3.5〜10倍、差分ビルドだと100倍以上速くなっているとのことで、大規模なプロジェクトほど恩恵が大きそうです。

HMR（保存してからブラウザに反映されるまでの時間）も明らかに速くなった感覚があって、細かいスタイル調整を繰り返す作業のストレスがかなり減りました！

🤔 移行で見た目が変わりやすいポイント

v4 への移行は、公式の npx @tailwindcss/upgrade でかなり自動でやってくれますが、見た目が少し変わるところがいくつかあります(・_・;)

移行したら、このあたりを画面で確認するのがおすすめです。

• 枠線の色: border だけ書いたときの色が、v3 の薄いグレーから「文字と同じ色」に変わった
• ring の太さ: ring だけ書いたときの太さが 3px から 1px になった
• プレースホルダーの色: 入力欄の薄い文字の色が少し変わった
• 対応ブラウザ: v4 は新しいブラウザ（Safari 16.4 以降など）が前提。古いブラウザの利用者が多いサイトは注意

特に枠線は、カードや入力欄の枠が急に濃くなるので、移行してすぐ気づくと思います👀

v3 と同じにしたいなら、CSS に1つ足しておけば揃います。

@layer base {
  *, ::after, ::before { border-color: var(--color-gray-200, currentColor); }
}

移行のプルリクでは、主な画面のスクリーンショットを前後で並べておくと、レビューする人も見比べやすいです✨

パパ系Webエンジニア〜愛用ガジェット一覧 🛍️

この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌

楽天ROOMで見る

🙌 まとめ

Tailwind CSS v4 の移行で、一番うれしかったのは設定ファイルが減ったことでした。

tailwind.config.js の管理から解放されて、CSS だけで完結する設計は長期運用でもかなり楽になりそうだと感じています。

移行ツールも用意されているので、新しいプロジェクトはもちろん、既存プロジェクトでも試してみる価値はあります。ぜひ試してみてください🙌

※ Tailwind CSSのバージョンによって仕様が変わることがあります。最新情報は Tailwind CSS公式ドキュメント をご確認ください👀