tailwindで自動的に検出できないクラスを明示的に登録しておくtips
開発環境
- react 19.0.0
- tailwindcss 3.4.16
前提
Tailwind CSS は JIT（Just-In-Time）モード により、実際にプロジェクト内で使用されているクラスを解析して必要な CSS を生成します。
つまり、コード上に現れないクラス名はビルド対象外になり、スタイルが当たらない仕様です。
この挙動は効率的でありがたい反面、
たとえばテンプレートリテラルで bg-${color}-500 のようにクラス名を動的に生成するケースでは、Tailwind がそのクラスを検出できずに「反映されない」という問題が発生します。
以前はこのようなケースで、仕方なく次のように style プロパティで強引に色指定していました。
<div style={{ backgroundColor: color }}>...</div>もちろんこれは「Tailwind の恩恵を受けられない」やり方で、保守性も一貫性も損なわれます。 今回は、そんなときに便利な明示的登録の方法を紹介します。
本題
適当なファイルを用意する
まず、プロジェクト直下や src/ 配下などに txtファイルを用意します。 ここでは src/tailwind-allowlist.txtという名前にしています。
構成例：
src/
├─ components/
├─ index.css
└─ tailwind-allowlist.txtbg-red-500
bg-blue-500
bg-green-500
text-gray-400
text-gray-600
text-gray-8001 行に 1 クラスずつ、Tailwind に認識させたいクラス名を記述します。
Tailwind に認識させる
次に、このファイルを Tailwind のビルド対象に明示的に含めます。 Tailwind CSS v3 以降では、@sourceディレクティブを使うことで簡単に追加できます。
以下のように、src/index.css（またはエントリポイントの CSS ファイル）で読み込みます。
@source "tailwind-allowlist.txt";これで、tailwind-allowlist.txtに記載したクラスがビルド時に検出対象となり、 コード内で動的生成していても正しくスタイルが適用されるようになります。
動的クラスの例
// Badge.tsx
interface BadgeProps {
color: 'red' | 'blue' | 'green';
name: string;
}
export const Badge = ({ color, name }: BadgeProps) => {
return (
<div className={`bg-${color}-500 text-white px-3 py-1 rounded-md`}>
{name}
</div>
);
}このように、bg-${color}-500を動的に指定しても問題ありません。 事前に tailwind-allowlist.txtに該当クラスを列挙しておけば、Tailwind がしっかりスタイルを生成してくれます。
さいごに
Tailwind CSS の JIT コンパイルは非常に強力ですが、「コードに直接書かれていないクラスは検出しない」という仕様を理解していないと、思わぬところでスタイルが崩れます。
今回紹介したように、明示的にクラスを登録しておくことで、動的クラスを安心して使えるようになります。
以前のように style={{ backgroundColor: color }}で強引に設定していたやり方はもう不要です。
Tailwind のエコシステム内で完結できるこの方法を活用して、クリーンな実装を保ちましょう。
もちろん、公式ドキュメントで紹介されている「常にプロパティを静的クラス名にマッピングする」方法も有効ですので、状況に応じて使い分けできると良いです。
function Button({ color, children }) {
const colorVariants = {
blue: "bg-blue-600 hover:bg-blue-500",
red: "bg-red-600 hover:bg-red-500",
};
return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}