TailwindCSS v4 でのセーフリスト実装方法

問題の背景

TailwindCSS v4 では設定方法が大幅に変更され、JavaScriptベースの構成（tailwind.config.js）からCSSベースのアプローチへ移行しました。これに伴い、v3で利用できたsafelistプロパティが削除されました。具体的には次の制約が発生します：

• 動的に生成されるクラス（例: grid-cols-1, grid-cols-2...）をビルドに強制的に含められない
• バリアント（sm:, md: など）付きのクラスパターンを一括指定する方法が消失
• 代替案としてダミーHTMLや@applyを使用する必要があるが、これは冗長で保守性が低い

// v3で可能だった設定（v4では非対応）
export default {
  safelist: [{
    pattern: /grid-cols-+/,
    variants: ["sm", "md", "lg", "xl"]
  }]
}

解決策：TailwindCSS v4.1+ での最新アプローチ

v4.1から導入された@source inline()を使用することで、v3のsafelistと同等以上の機能を実現できます。

基本構文

CSSファイル内で直接クラスを指定：

@source inline('クラスパターン');

実践例：grid-cols クラスのセーフリスト

/* 1〜12のgrid-colsクラスを全バリアントで生成 */
@source inline('{sm:,md:,lg:,xl:,}grid-cols-{{1..12}}');

::tip カンマの重要性
バリアント末尾のカンマ（例: sm:,）は基本クラス（バリアントなし）を含むことを意味します。省略するとバリアント版のみ生成されます。 :::

応用パターン

1. 複数値を明示的に指定:

   @source inline('{hover:,}bg-red-{50,100,200}');

2. 範囲とステップ指定（100〜900を50刻み）:

   @source inline('bg-blue-{{100..900..50}}');

3. 複合パターン:

   /* 全方向のpadding/marginクラスを生成 */
   @source inline("{m,p}{x,y,t,b,l,r}-{1..10}");

WARNING

過度な使用に注意
safelistを多用するとCSSバンドルサイズが肥大化します。本当に必要なクラスのみを対象にしましょう。

バージョン別対応ガイド

v4.1+ 推奨方法

機能	コード例	説明
基本構文	@source inline('underline');	単一クラス指定
バリアント付与	@source inline('{hover:,focus:}bg-red-500');	状態別バリアント
数値範囲	@source inline('p-{{4..12}}');	ステップ指定なし
複合パターン	@source inline('col-span-{1,2,3}');	複数値明示指定

v4.0.x での代替案

v4.1未満では公式のセーフリスト機能が存在しません。代替手段として：

1. クラス参照ファイルを作成:

   // classes.js
   export const classes = [
     'sm:grid-cols-1', 
     'md:grid-cols-2',
     // ...
   ];

2. ビルドスクリプトでファイル生成:

   // generate-classes.js
   import fs from 'fs';
   import { classes } from './classes.js';
   
   fs.writeFile('safelist.txt', classes.join('\n'), (err) => {
     if (err) console.error(err);
     else console.log('Safelist created!');
   });

3. 生成ファイルをインポート:

   @source "safelist.txt";

実装時のベストプラクティス

1. 必要なクラスのみ指定
   全バリアントを一律追加せず、実際に使用する組み合わせに限定

   - @source inline('{sm:,md:,lg:,xl:,}grid-cols-{{1..12}}');
   + @source inline('{sm:,lg:}grid-cols-{{1..6}}');

2. 数値範囲は具体的に定義
   無限範囲を指定するとビルドパフォーマンスが低下

   /* 推奨: 現実的な範囲指定 */
   @source inline('gap-{{4..32..4}}');

3. 複数のセーフリストは分離
   各クラスグループは独立した@sourceで宣言

   @source inline('max-w-{sm,md,lg}');
   @source inline('bg-{red,blue}-500');

4. バリアントの省略ルールを活用
   不要なプリフィックスを省いてCSSサイズを削減

   /* 基本クラスのみ必要な場合 */
   @source inline('grid-cols-{{1..6}}');

参照リソース

• 公式ドキュメント: Safelisting Utilities
• GitHub Discussion: v4 Safelist
• 実装機能の技術背景

v4のセーフリスト機構は初期バージョンに比べて強化され、CSSベースの新アーキテクチャに適応した柔軟なクラス管理が可能になりました。@source inline()を適切に活用することで、動的クラスの扱いを効率化できます。