インポートと仮想モジュール

Markdownとして表示 GitHubで編集ドキュメント: 3843abd

TailwindPHPはコンパイル前に@importルールを解決します。インポート先には、組み込み仮想モジュール（tailwindcssなど）、importPathsオプションによるディスク上のファイル、カスタムリゾルバーが返す任意のものを指定できます。

仮想モジュール

@import "tailwindcss"は、多くのプロジェクトで使われるエントリーポイントです。次の4行に展開されます。レイヤー順序の宣言と、それぞれのカスケードレイヤーに割り当てられた3つのサブインポートです。

CSS

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

各サブインポートは、それぞれ単独でインポートできる仮想モジュールです。利用可能な仮想モジュールは次のとおりです。

モジュール	内容
`tailwindcss`	完全なバンドル: テーマ + Preflight + ユーティリティ。
`tailwindcss/theme.css`	テーマ変数のみ（色、基本スペーシング、ブレークポイントなど）。
`tailwindcss/preflight.css`	Preflightの基本リセット。
`tailwindcss/utilities.css`	ユーティリティレイヤー。
`tw-animate-css`	`tw-animate-css`アニメーションユーティリティ。

各パーツを個別にインポートすると、Preflightを省いたり、レイヤーの順序を変更したりできます（下記参照）。

tw-animate-cssによるアニメーション

tw-animate-cssはTailwindCSS v4向けのアニメーションライブラリで、tailwindcss-animateのドロップイン代替です。組み込み仮想モジュールとして提供されるため、ユーティリティレイヤーと一緒にインポートすると、入場・退場アニメーションのクラスも他のユーティリティと同様にコンパイルされます。

CSS

@import "tw-animate-css";
@import "tailwindcss/utilities.css";

アニメーションユーティリティには次のものがあります。

入場 / 退場 — animate-in, animate-out
フェード — fade-in, fade-out
ズーム — zoom-in, zoom-out
回転 — spin-in, spin-out
ぼかし — blur-in, blur-out
スライド — slide-in-from-top / -bottom / -left / -rightと対応するslide-out-to-*、およびRTL対応の-start / -end
タイミング — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate、fill-mode-none / -forwards / -backwards / -both
再生状態 — running, paused
コンポーネントアニメーション — accordion-down / accordion-up, collapsible-down / collapsible-up、caret-blink

これらのクラスは他のユーティリティと同様にTailwindのバリアントとスタックできるため、shadcn/uiのダイアログやドロップダウンのパターンにそのまま適用できます。

`importPaths`オプション

ファイルシステムを使って@importを解決するには、generate()の配列形式でimportPathsを渡します。単一のパス、ディレクトリ、またはそれらの配列を指定できます。

PHP

use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);

ネストされたインポート

読み込んだファイル内のインポートは、そのファイルを基準に解決されます。/path/to/styles.cssに@import "./components/buttons.css"が含まれる場合、パスは/path/to/を基準に解決されます。

CSS

/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

@theme {
    --color-brand: #3b82f6;
}

重複排除

同じファイルまたは仮想モジュールを複数回インポートしても、最初の読み込み後は何も起こりません。@import "tailwindcss"行の繰り返しや、同じ部分ファイルをインポートする2つのファイルは自動的に重複排除されます。これにより循環インポートも防げます。

カスタムリゾルバー

仮想ファイルシステム、データベース、その他のファイルシステム以外のソースでは、呼び出し可能な値をimportPathsとして渡します。インポートURIと、インポートの解決先となる基準ディレクトリを受け取り、CSSまたはnullを返します。

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);

$uriがnullの場合（最初の呼び出しで、2つ目の引数もnull）、エントリーCSSを返します。それ以外のURIでは、そのCSSの内容を返すか、nullを返してファイルシステム検索にフォールバックします。見つからない場合、インポートは何も通知されずにスキップされます。

事前確認

Preflightは、modern-normalizeを基盤とした、Tailwind独自の基本リセットです。ブラウザー間の差異を整え、ユーティリティが予測どおりに動作するようにします。既定のマージンを削除し、見出しやリストのスタイルを解除し、画像をブロック要素にし、border-widthだけでボーダーが描画されるようにボーダースタイルをリセットし、ボタンがフォントを継承するようにするなどの処理を行います。

Preflightは@import "tailwindcss"に含まれているため、完全なバンドルをインポートすれば、すでに利用できます。

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);

Preflightの拡張

@layer baseを使うと、Preflightの上に独自の基本スタイルを追加できます。

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);

Preflightを無効にする

既存のプロジェクトに組み込む場合は、必要なパーツだけをインポートし、Preflightの行を省略します。

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);

インポート修飾子

Tailwindのファイルを個別にインポートする場合、修飾子は適用対象のインポートに指定します。

CSS

/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);

参照インポート

@import "…" referenceは定義だけを読み込むファイルです。@themeの値、ファイル内で定義された@utilityと@custom-variantは使用できますが、そのファイルからCSSは出力されません。ファイルの内容を@media reference { … }で囲むのと同じで、こちらの書き方もできます。

CSS

@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}

bg-brandはbackground-color: var(--color-brand, #f00);にコンパイルされ、--color-brand宣言は出力されません。

現在のリリースにおける制限は2つです（#14）。

参照インポートと@media referenceブロックは、tailwindcssまたはtailwindcss/utilities.cssの@importの後に置いてください。前に置くと、出力全体が空になります。
組み込み仮想モジュール（@import "tailwindcss" reference;）へのreferenceは、まだ効果がありません。テーマ、Preflight、ユーティリティは引き続き出力されます。

テーマ変数についてはTheme、クラス名のスキャン対象ファイルを制御する方法については@sourceを参照してください。