Tailwind CSS v4 - CSS-first設定と移行時の注意点

Tailwind CSS v4とは

Tailwind CSS v4.0は、2025年1月22日に公開されたメジャーアップデートです。engineの刷新だけでなく、JavaScript中心だった設定をCSSへ移すCSS-first configuration、template fileの自動検出、Vite向け公式pluginなどが導入されました。

以前のこの記事は「Rustベースのengineで10倍高速化」と一括して説明していました。しかし公式の安定版記事は、full build、増分build、新しいCSSを生成しない増分buildを分けて計測しています。

速度はprojectと処理内容で変わります。この記事では「常に10倍」とは表現せず、公開済み機能と移行時の注意点を中心に整理します。

v4の主な変更

v3のtailwind.config.jsを使う構成とは考え方が変わります。

Viteで導入する

Vite projectでは公式pluginを利用できます。

npm install tailwindcss @tailwindcss/vite

vite.config.tsへpluginを追加します。

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

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

CSSではTailwindをimportします。

@import "tailwindcss";

これで基本的なutilityを利用できます。

<main class="mx-auto max-w-3xl px-6 py-12">
  <h1 class="text-3xl font-bold">Tailwind CSS v4</h1>
  <p class="mt-4 text-slate-600">CSS-first configuration</p>
</main>

frameworkごとに公式のinstallation guideがあります。古いblog記事の設定をそのまま混ぜず、利用中のframework向け手順を確認します。

PostCSSで導入する

Vite以外ではPostCSS pluginを利用できます。

npm install tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

v3でtailwindcss packageを直接PostCSS pluginとして指定していたprojectは、@tailwindcss/postcssへ変更します。

CSS-first configuration

v4では、color、font、breakpointなどのtheme tokenをCSS内で定義できます。

@import "tailwindcss";

@theme {
  --font-display: "Noto Sans JP", sans-serif;
  --color-brand-500: oklch(0.62 0.18 250);
  --breakpoint-3xl: 120rem;
}

定義したtokenからutilityが生成され、通常のCSS custom propertyとしても参照できます。

.site-title {
  color: var(--color-brand-500);
  font-family: var(--font-display);
}

design tokenをJavaScriptとCSSの両方へ重複定義せずに済む点がv4の特徴です。一方、既存pluginや共有presetがJavaScript configを前提にしている場合は移行方法を確認します。

contentの自動検出

v4は、class名を探すsource fileを自動検出します。.gitignore内のpathやbinary fileなどは対象外になります。

自動検出されない外部component packageなどを明示する場合は、@sourceを利用できます。

@import "tailwindcss";
@source "../node_modules/@example/ui";

class名を文字列連結で動的生成すると、source codeから完全なclass名を検出できない問題はv4でも残ります。

// 検出されない可能性がある
const className = `text-${color}-600`;

// 完全なclass名を対応付ける
const colors = {
  red: "text-red-600",
  blue: "text-blue-600",
};

production build後に、条件分岐でしか表示されないclassも含めて確認してください。

modern CSSの利用

Tailwind CSS v4は、cascade layers、@property、color-mix()、logical propertiesなど、modern browserのCSS機能を活用します。

公式upgrade guideでは、v4はSafari 16.4以降、Chrome 111以降、Firefox 128以降を対象としています。これより古いbrowserをsupportする必要があるprojectには、v3.4を継続する選択肢が案内されています。

社内端末、WebView、古いOSを対象にする場合は、一般的なbrowser shareではなく実際のsupport要件を確認します。

公式ベンチマークの読み方

Tailwind公式のv4.0記事では、Catalyst projectを使った測定例として次を掲載しています。

これはTailwind teamが特定projectで測定した中央値です。あらゆるprojectで同じ結果になる保証ではありません。

「最大5倍」「100倍以上」という要約は、異なる処理を指します。full buildと、新しいutilityを生成しない増分buildを混同しないでください。

自分のprojectでは、初回build、class追加後のbuild、既存classだけを編集したbuildを分けて測定します。

v3から移行する

公式upgrade toolは、dependency、configuration、templateの変更の多くを自動化します。Node.js 20以降が必要です。

npx @tailwindcss/upgrade

公式guideは、新しいbranchで実行してdiffを確認するよう案内しています。

git switch -c chore/tailwind-v4
npx @tailwindcss/upgrade
npm run build

自動変換後に次を確認します。

• tailwind.config.jsのthemeとpluginが移行された
• PostCSS plugin名が新しいpackageになった
• @tailwind directiveが@importへ変わった
• browser support要件を満たす
• deprecated utilityの置換で見た目が変わっていない
• border、shadow、ringなどdefaultの変更を確認した
• arbitrary valueやCSS variableが意図通り動く
• production buildで全classが生成される

移行を急がなくてよい場合

古いbrowserをsupportする必要がある、利用pluginがv4未対応、現在のv3 projectが安定しており変更の利点が小さい場合は、v3.4を維持しながら移行条件を整える方法があります。

major updateは、build速度だけで決めるものではありません。design system、plugin、browser、CI、visual regression testを含めて判断します。

まとめ

• Tailwind CSS v4は2025年1月22日に公開された
• CSS-first configurationと自動content検出が中心的な変更
• ViteとPostCSSでは利用する公式packageが異なる
• modern CSSを使うためbrowser support要件がある
• 公式benchmarkは処理条件ごとに差が異なる
• upgrade toolの結果は必ずdiffと画面で確認する

参考リソース

• Tailwind CSS v4.0公式発表
• Tailwind CSS Upgrade Guide
• Tailwind CSS Compatibility
• Tailwind CSS Installation

×

PR

×

PR