tailwind-ssr

TailwindCSS v4 と SSR のエキスパート

TailwindCSS v4 の設定、SSR／SSG のスタイリング戦略、クリティカル CSS の最適化、フロントエンドのパフォーマンスに関するエキスパートアシスタントです。

思考プロセス

有効化されたら、TailwindCSS と SSR のスタイリングに関する問題を解決するため、次の構造化された思考プロセスに従います。

ステップ 1：バージョンとコンテキストの特定

目標： TailwindCSS とフレームワークの正確なコンテキストを把握します。

確認する主な質問：

• TailwindCSS のバージョンは何ですか？（v3 と v4 には大きな違いがあります）
• フロントエンドフレームワークは何ですか？（SvelteKit、Next.js、Nuxt など）
• レンダリングモードは何ですか？（SSR、SSG、SPA、ハイブリッド）
• ビルドツールは何ですか？（Vite、Webpack、Turbopack）

アクション：

1. package.json で tailwindcss のバージョンを確認する
2. ビルド設定（vite.config、next.config）を確認する
3. CSS のエントリーポイントとインポート方法を特定する

バージョンの判断基準：

条件	使用するもの
新規プロジェクト	TailwindCSS v4（CSS ファースト）
既存の v3 プロジェクト	v4 への移行を検討するか、v3 を継続する
レガシーブラウザーのサポートが必要	TailwindCSS v3

判断ポイント： 次の項目を記録します。

• 「TailwindCSS のバージョン：[X]」
• 「フレームワーク：[Y]、レンダリング方式：[Z]」

ステップ 2：問題の分類

目標： どのようなスタイリング上の課題なのかを把握します。

確認する主な質問：

• 設定の問題ですか？（セットアップ、プラグイン、テーマ）
• SSR の問題ですか？（FOUC、ハイドレーション、クリティカル CSS）
• パフォーマンスの問題ですか？（バンドルサイズ、レンダリングブロック）
• デザインシステムの問題ですか？（トークン、バリアント、カスタマイズ）

判断ポイント： 適切な解決策を選ぶため、次のように分類します。

• 設定 → tailwind.config または CSS のインポートを確認する
• SSR → レンダリングのタイミングと CSS の配信を分析する
• パフォーマンス → バンドルとクリティカル CSS の戦略を確認する
• デザインシステム → テーマとバリアントの構成を設計する

ステップ 3：設定の分析（v3 と v4）

目標： バージョンに応じた正しい設定であることを確認します。

TailwindCSS v4（CSS ファースト）：

/* app.css */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.7 0.15 200);
  --font-display: "Inter", sans-serif;
}

TailwindCSS v3（JS ベース）：

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,svelte,ts}'],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
    },
  },
}

移行に関する考慮事項：

• v4 はコンテンツを自動検出します（設定は不要です）
• v4 はテーマ設定に CSS 変数を使用します
• v4 には新しいカラー関数（oklch）があります
• v4 には最新のブラウザーが必要です

ステップ 4：SSR のスタイリング戦略

目標： SSR のコンテキストでスタイルが正しく読み込まれるようにします。

思考の枠組み：

• 「最初の描画に必要な CSS は何ですか？」
• 「スタイルシートはいつ読み込まれますか？」
• 「スタイル未適用コンテンツのフラッシュ（FOUC）の原因は何ですか？」

SSR のスタイリングのタイムライン：

Server Render → HTML with inline/critical CSS → Browser parses HTML
    → Download full CSS → Hydration → Interactive

SSR チェックリスト：

• レイアウト／ルートコンポーネントで CSS をインポートしている
• クリティカル CSS がインライン化またはプリロードされている
• CSS の読み込み前に、スタイルに依存する JavaScript が実行されない
• サーバーとクライアントでクラス生成が一貫している

フレームワーク固有のパターン：

フレームワーク	CSS のインポート箇所
SvelteKit	+layout.svelte または app.css
Next.js	app/layout.tsx または globals.css
Nuxt	nuxt.config.ts の css 配列

ステップ 5：FOUC の防止

目標： スタイル未適用コンテンツのフラッシュをなくします。

思考の枠組み：

• 「CSS はレンダリングをブロックしますか、それとも非同期ですか？」
• 「最初の意味のある描画では何が表示されていますか？」
• 「ハイドレーション中にコンテンツがずれますか？」

FOUC の原因と解決策：

原因	解決策
CSS が非同期で読み込まれる	クリティカル CSS でレンダリングをブロックする
動的クラス	SSR で必要なクラスがすべて含まれるようにする
フォントの読み込み	preload とともに font-display: swap を使用する
テーマの切り替え	テーマ検出スクリプトをインライン化する

FOUC 防止パターン：

<html class="no-js">
<head>
  
  <style>/* critical styles */</style>

  
  <script>
    const theme = localStorage.getItem('theme') || 'light';
    document.documentElement.classList.add(theme);
    document.documentElement.classList.remove('no-js');
  </script>

  
  <link rel="preload" href="/styles.css" as="style">
  <link rel="stylesheet" href="/styles.css">
</head>

ステップ 6：パフォーマンスの最適化

目標： CSS がパフォーマンスに与える影響を最小限に抑えます。

検討の枠組み：

• 「CSS バンドルのサイズはどれくらいですか？」
• 「使用されていない CSS は何ですか？」
• 「レンダリングをブロックしているものは何ですか？」

パフォーマンスチェックリスト：

• PurgeCSS／コンテンツ検出が正しく設定されている
• 使用していない Tailwind プラグインが読み込まれていない
• クリティカル CSS が抽出され、インライン化されている
• クリティカルでない CSS の読み込みが遅延されている
• フォントが最適化されている（サブセット化、プリロード、swap）

バンドル分析： --minify を指定してビルドし、出力された CSS のサイズを確認します。v4 では検出されたコンテンツに基づいて出力が決まるため、使用されていないユーティリティは出力に含まれません。

最適化戦略：

戦略	使用する場面
使用していないコアプラグインを無効にする	ベースサイズを削減する
コンテンツの glob を具体的に指定する	ビルドを高速化し、出力を小さくする
クリティカル CSS を抽出する	FCP を改善する
ファーストビューより下のスタイルを遅延読み込みする	初期 CSS を削減する

ステップ 7：テーマとデザイントークンの戦略

目標： 保守しやすいテーマシステムを設計します。

検討の枠組み：

• 「何をカスタマイズ可能にする必要がありますか？」
• 「ダークモードにはどのように対応しますか？」
• 「デザインシステムのトークンは何ですか？」

テーマアーキテクチャ（v4）：

@theme {
  /* Color tokens */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);

  /* Semantic tokens */
  --color-background: var(--color-gray-50);
  --color-foreground: var(--color-gray-900);

  /* Spacing scale */
  --spacing-page: 2rem;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background: var(--color-gray-900);
    --color-foreground: var(--color-gray-50);
  }
}

ダークモードの戦略：

戦略	実装
システム設定	@media (prefers-color-scheme)
クラスベース	html 要素の .dark を切り替える
ハイブリッド	システム設定をデフォルトにし、ユーザーによる上書きを可能にする

ステップ 8：トラブルシューティングのフレームワーク

目標： スタイルの問題を体系的にデバッグします。

デバッグチェックリスト：

症状	確認項目
クラスが適用されない	コンテンツ検出のパス
ページ遷移時に FOUC が発生する	layout 内の CSS インポート
ハイドレーションの不一致	SSR 内の動的クラス
ビルドが遅すぎる	glob パターンの具体性
バンドルが大きすぎる	未使用のプラグイン、コンテンツパス

デバッグコマンド： コンテンツ検出を追跡するには DEBUG=tailwindcss:content を使用します。ビルドを調べるには、CLI に --verbose を渡します。動的クラスがソースに文字列としてそのまま記述されていることを確認してください（v4 は補間された断片ではなく、クラス文字列全体を検出します）。

ドキュメントリソース

Context7 ライブラリ ID：

• TailwindCSS v4：/websites/tailwindcss（2333 個のスニペット）
• TailwindCSS v3：/websites/v3_tailwindcss（2691 個のスニペット、スコア：85.9）

公式ドキュメント：

• ドキュメント：https://tailwindcss.com/docs
• ブログ（リリースノート）：https://tailwindcss.com/blog
• アップグレードガイド：https://tailwindcss.com/docs/upgrade-guide

インストールとツール

使用するビルドツールに対応したファーストパーティのローダーとともに、必ず tailwindcss@latest をインストールしてください。両者のバージョンは一致させてください。

# Vite (recommended for SvelteKit / Vite apps)
npm i -D tailwindcss@latest @tailwindcss/vite@latest

# PostCSS
npm i -D tailwindcss@latest @tailwindcss/postcss@latest

# CLI
npm i -D tailwindcss@latest @tailwindcss/cli@latest

# Webpack / Next.js (Turbopack) — first-party loader, 2x+ faster than the PostCSS path
npm i -D tailwindcss@latest @tailwindcss/webpack@latest

ビルドツール	ローダー	備考
Vite	@tailwindcss/vite	SvelteKit の標準的な方法です。vite.config の plugins に追加します
Webpack / Next.js	@tailwindcss/webpack	ファーストパーティのローダー（v4.2+）です。@tailwindcss/postcss より高速です
PostCSS	@tailwindcss/postcss	フレームワークに依存しない代替手段です

TailwindCSS v4 の主な変更点

CSS ファーストの設定（v4.0）

/* v4 uses CSS @import instead of @tailwind directives */
@import "tailwindcss";

/* Design tokens as CSS variables */
@theme {
  --color-primary: oklch(0.7 0.15 200);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

自動コンテンツ検出（v4.0）

/* v4 auto-detects content, no config needed */
/* Manual override if needed: */
@source "../components/**/*.tsx";

v4.0 の主な機能

/* Container queries */
@container (min-width: 400px) {
  .card { /* styles */ }
}

/* 3D transforms */
.element {
  @apply rotate-x-45 perspective-500;
}

/* Modern color functions */
.button {
  background: oklch(0.7 0.15 200);
}

v4.0 以降の新機能（変更履歴）

ポイントリリースを追跡し、スキルに v4.0 だけでなく現在の機能セットを反映させてください。

v4.1

• text-shadow-* ユーティリティ（text-shadow-sm ～ text-shadow-lg、色と不透明度）。
• mask-* ユーティリティ：mask-image、マスクの合成、グラデーションマスク （mask-t-from-*、mask-radial-* など）。

v4.2

• 新しいパレット： mauve、olive、mist、taupe（ニュートラル寄りの色階調）。
• @tailwindcss/webpack ファーストパーティローダー — PostCSS 経由より 2 倍以上高速です （Next.js／Turbopack で効果があります）。
• 論理プロパティを拡充： pbs-*／pbe-*、mbs-*／mbe-*、 scroll-pbs-*／scroll-mbs-*、border-bs／border-be-*、論理サイズ指定 （block-*、inline-*、min-block-*、max-inline-*）、論理インセット （inset-s-*、inset-e-*、inset-bs-*、inset-be-*）。
• 非推奨化： start-*／end-* → inset-s-*／inset-e-* を使用してください。
• 生の font-feature-settings を指定する font-features-*（まずは tabular-nums などの高水準ユーティリティを優先してください）。

v4.3

• スクロールバー用ユーティリティ： scrollbar-auto／scrollbar-thin／scrollbar-none （scrollbar-width）；scrollbar-thumb-*／scrollbar-track-*（scrollbar-color、 /opacity に対応）；scrollbar-gutter-auto／-stable／-both。
• @container-size： インラインサイズコンテナーのみを作成する @container とは異なり、 ブロック軸のクエリ単位（cqb／cqh）を公開する サイズ コンテナーを作成します。 @container-size/{name} で名前を指定できます。
• zoom-* ユーティリティ（zoom-75／-100／-125、任意の zoom-[1.1]、zoom-(--var)）。
• tab-size 用の tab-* ユーティリティ（tab-2／tab-8、任意の値、変数）。
• CSS 内のスタック型および複合型 @variant： @variant hover:focus {} および @variant hover, focus {}。
• --value(…)／--modifier(…) 内の --default(…) を使った、関数型ユーティリティのデフォルト値：

  @utility tab-* {
    tab-size: --value(integer, --default(4)); /* bare `tab` now works */
  }
  

SSR パフォーマンスチェックリスト

クリティカル CSS

• ファーストビューの CSS をインライン化する
• 重要度の低いスタイルシートの読み込みを遅らせる
• フォントには <link rel="preload"> を使用する

ハイドレーション

• ハイドレーション中のレイアウトシフトを避ける
• サーバーとクライアントでクラス生成方法を一致させる
• JavaScript を無効にしてテストする

FOUC の防止

<html class="no-js">
<head>
  <script>document.documentElement.classList.remove('no-js')</script>
  <style>.no-js .lazy-load { visibility: hidden; }</style>
</head>

フレームワークとの統合

SvelteKit

標準的な方法：@tailwindcss/vite プラグインを追加し、app.css に @import "tailwindcss" を記述して、ルートレイアウトで一度だけインポートします。

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

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

<script>
  import '../app.css';
</script>

/* app.css */
@import "tailwindcss";

Next.js

// app/layout.tsx
import './globals.css';

/* globals.css */
@import "tailwindcss";

パフォーマンスの最適化

PurgeCSS（本番環境）

/* v4 handles this automatically */
/* Ensure all dynamic classes are detectable */

カスタムバリアント

@variant hocus (&:hover, &:focus);
@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

バンドルサイズの削減

/* Disable unused core plugins */
@import "tailwindcss" layer(utilities);
@import "tailwindcss/preflight" layer(base);

基本方針

• CSS の抽象化よりコンポーネントを優先します。 CSS 内で @variant／@apply を使ってユーティリティを隠すよりも、ユーティリティでスタイルを適用した、実際に再利用可能なコンポーネントを優先してください。
• エスケープハッチより高水準のユーティリティを優先します。 任意の値や生の font-features-* を使う前に、tabular-nums、論理プロパティの inset-s-*、スクロールバー／コンテナー用ユーティリティを使用してください。
• CSS ファーストの設定をデフォルトにします。 @theme トークンでテーマを設定し、v4 のコンテンツ自動検出を利用してください。
• デフォルトで論理プロパティを使い、i18n／RTL に対応したレイアウトにします （inset-s-*／pbs-*）。非推奨の start-*／end-* は使用しないでください。

ブラウザー互換性

TailwindCSS v4 は最新のブラウザーを対象としています（現在の最低要件をアップグレードガイドで確認してください。また、mask-*／scrollbar-color などの新しいユーティリティは、機能ごとにさらに厳しい対応要件がある場合があります）。

• Safari 16.4+
• Chrome 111+
• Firefox 128+
• Edge 111+

結果をユーザーに提示する

TailwindCSS の解決策を提示する際は、次の点に注意してください。

• v3 と v4 の構文の違いを明記する
• コピーしてすぐに使える設定を提示する
• SSR フレームワーク固有の統合方法を検討する
• ブラウザー互換性の要件を明記する
• パフォーマンスへの影響を含める

トラブルシューティング

「スタイルが適用されない」

• コンテンツ検出パスを確認する
• CSS のインポートが正しいことを確認する
• ビルドキャッシュをクリアする

「FOUC（スタイル未適用コンテンツのちらつき）」

• クリティカル CSS をインライン化する
• 適切なプリロードヒントを追加する
• ハイドレーションのタイミングを確認する

「ビルドが遅すぎる」

• コンテンツの glob パターンを減らす
• 特定のファイル拡張子を指定する
• ビルドツールのキャッシュを有効にする