コンテンツへスキップ

Tailwind CSS

BlockstudioにはTailwind CSS v4のサポートが組み込まれています。有効にすると、すべてのフロントエンドページがTailwindPHPを介してサーバーサイドでコンパイルされ、ファイルベースで自動キャッシュされます。ブロックエディターでは、バンドルされたTailwind CDNスクリプトにより、編集しながらライブプレビューを確認できます。

ビルド工程もCLIもNode.jsも不要です。

動作の仕組み

Blockstudioは、状況に応じて2つの異なるコンパイル方式を使います。

フロントエンド(サーバーサイド)

フロントエンドへのリクエストごとに、Blockstudioは出力バッファーを使ってページ全体のHTMLを取得し、すべてのCSSクラス候補を抽出します。実際に使われているCSSだけをコンパイルし、結果を</head>の前にインライン<style>タグとして挿入します。

コンパイルの流れ:

  1. WordPressが出力バッファーにページ全体のHTMLをレンダリングします
  2. TailwindPHP::extractCandidates()がHTMLをスキャンし、CSSクラス名の候補をすべて抽出します(高速な正規表現を使用し、コンパイルはしません)
  3. 候補をCSSの設定とともにソートしてハッシュ化し、キャッシュキーを作成します
  4. キャッシュヒット時:コンパイル済みのCSSをディスクから読み込み、挿入します
  5. キャッシュミス時:TailwindPHP::generate()がCSSをコンパイルし、キャッシュディレクトリに書き込んで挿入します

コンパイル済みのCSSは次のように挿入されます:

HTML
<style id="blockstudio-tailwind">
  /* compiled CSS */
</style>

これにはTailwindのpreflight(CSSリセット)と、該当するすべてのユーティリティクラスが含まれます。

エディター(クライアントサイド)

ブロックエディター内では、バンドルされたTailwind CDNスクリプト(Tailwind CSS v4のブラウザービルド)がクライアントサイドで実行されます。サーバーへの往復なしに、クラス名を入力するとすぐにライブプレビューが表示されます。CDNはエディター内でのみ読み込まれ、フロントエンドでは配信されません。

assets.reset.enabledが有効な場合、Blockstudioはエディターキャンバス内でTailwindの一般的なdisplayユーティリティとpositionユーティリティも復元します。これにより、flex、grid、absolute、fixed、stickyなどのラッパーレベルのクラスが、WordPressのエディターブロックラッパールールで上書きされるのを防ぎ、ユーティリティ主導のレイアウトがフロントエンドに近い表示になります。

Tailwindを有効にする

blockstudio.jsonにtailwind設定を追加します:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true
  }
}

または、フィルターで有効にします:

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

enabledがtrueの場合、すべてのフロントエンドページでTailwind CSSが自動的にコンパイルされ、挿入されます。ブロックテンプレート、テーマテンプレート、the_contentフィルターなど、ページ出力に含まれるあらゆるHTMLでTailwindユーティリティクラスを使用できます。

フロントエンドの出力

コンパイル済みのCSSはデフォルトでインラインになり、以前のバージョンと同じ出力を維持します。共有ルールが多いサイトでは、コンテンツハッシュ付きスタイルシートを選択できます:

JSON
{
  "tailwind": {
    "enabled": true,
    "output": "link"
  }
}

"output": "link"は既存のtailwind/{content-hash}.cssキャッシュファイルを<link rel="stylesheet">として出力します。ランタイムID、候補、エンジン、CSS入力が変わるとURLも変わるため、ブラウザーやエッジキャッシュは古いURLを安全に保持できます。このキャッシュスコープには、ウェブサーバーまたはCDNで長期間有効なCache-Control: public, immutableヘッダーを設定してください。

デフォルトのキャッシュルートはwp-contentの配下にある公開領域です。cache.pathが非公開の絶対パスのボリュームを指している場合、既存のblockstudio/files/urlフィルターでtailwindスコープ用の公開URLが指定されない限り、BlockstudioはインラインCSSにフォールバックします:

PHP
add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope): string {
        if ('tailwind' !== $scope) {
            return $url;
        }

        return 'https://static.example.com/blockstudio/' . basename($path);
    },
    10,
    3
);

テンプレート構成ヘルパー

Blockstudioは、バンドルされた同じTailwindPHPエンジンをPHPテンプレートに提供します。テーマ側にコピーや代替実装を用意する必要はありません:

PHP
$classes = bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4

$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => [
            'sm' => 'h-8 px-3',
            'lg' => 'h-12 px-6',
        ],
    ],
    'defaultVariants' => [
        'size' => 'sm',
    ],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);

bs_tw_merge()はネストされたクラス値を受け取り、競合するTailwindユーティリティを解決します。bs_tw_variants()は、ベース、バリアント、デフォルトバリアント、複合バリアント、class、classNameに対応したCVA形式の呼び出し可能オブジェクトを返します。

設定

Tailwind v4ではCSSを中心とした設定方式を採用しています。JavaScript設定ファイルを使う代わりに、@themeディレクティブを使い、設定をCSSとして直接記述します。

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
  }
}

configの値はCSS文字列で、@import "tailwindcss"ディレクティブの後に追加されます。ここでは有効なTailwind v4のCSS構文を使用できます:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
  }
}

複数行の設定には、フィルターを使う方法がより扱いやすくなります:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@theme {
    --color-primary: #3b82f6;
    --color-secondary: #10b981;
    --font-family-heading: 'Inter', sans-serif;
    --breakpoint-xs: 30rem;
}

@layer base {
    body {
        font-family: var(--font-family-sans);
    }
}

@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .btn-primary { @apply bg-blue-500 text-white hover:bg-blue-600; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

カスタムユーティリティクラス

再利用可能なクラスの別名を定義するには、設定文字列でTailwindの@applyディレクティブとともに@layer utilitiesを直接使います:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; } @layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .section { @apply py-16 px-4 max-w-7xl mx-auto; } }"
  }
}

これにより、標準のTailwindユーティリティと合わせてこれらのクラスもコンパイルされます。フロントエンド(サーバーサイドコンパイル)とエディター(CDNプレビュー)の両方で使用できます。

BlockstudioはTailwindの標準的なカスケードレイヤー順序を維持します: theme、base、components、その後にutilitiesです。これはTailwind CSSと一致するため、後のレイヤーのルールが期待どおりに前のレイヤーを上書きできます。

クラスフィールドの型

オートコンプリートを使いながらブロックのclassesフィールドでTailwindクラスを使うには、フィールドにtailwind: trueを設定します:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}

tailwindがtrueの場合:

  • フィールドにTailwindクラス一覧全体から候補が表示されます
  • ライブプレビュー用にTailwind CDNスクリプトがエディターで読み込まれます
  • クラスはブロック属性にスペース区切りの文字列として保存されます

テンプレートでクラスの値を使用します:

PHP
<div class="<?php echo $a['classes']; ?>">
  <!-- block content -->
</div>

設定リファレンス

オプション 型 デフォルト 説明
enabled boolean false フロントエンドでTailwind CSSのコンパイルを有効にする
config string "" Tailwind v4のCSS中心の設定文字列

JSONで設定

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: pink; }"
  }
}

フィルターで設定

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

add_filter('blockstudio/settings/tailwind/config', function () {
    return '@theme { --color-brand: pink; }';
});

キャッシュ

Blockstudioは、Tailwindのユーティリティベースの構造に合わせた独自のキャッシュ戦略を採用しています。

キャッシュの仕組み

ページ全体のHTMLをハッシュ化する代わりに(nonce、タイムスタンプ、その他の動的コンテンツによってリクエストごとにキャッシュが無効になるため)、BlockstudioはHTMLからCSSクラス候補だけを抽出します。候補をCSS設定とともにソートしてハッシュ化し、安定したキャッシュキーを生成します。

つまり、次のようになります:

  • 同じTailwindクラスのセットを使用する2つのページは、CSSファイルを共有キャッシュします。HTMLが完全に異なっていても同様です。
  • nonce、ログインユーザー向けバー、コメント数、タイムスタンプなどの動的コンテンツは、キャッシュを無効化しません。
  • キャッシュが無効になるのは、ページ上のCSSクラスのセットまたはTailwindの設定が変更された場合のみです。

ランタイムが論理的な検出ソースを使用する場合、選択されたソースとランタイムコンテキストもキャッシュの名前空間に含まれます。最後に正常だったCSSはプレビューごとに分離され、あるソースの選択から別の選択へ漏れることはありません。

キャッシュの場所

キャッシュファイルは次の場所に保存されます。

コード
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

設定されたcache.path、現在のマルチサイト識別情報、完全なランタイム識別情報によって、正確なプレフィックスが決まります。各ファイルにはMD5ハッシュを使った名前が付けられます。 {hash}.css。

キャッシュのクリア

再コンパイルを強制するには、キャッシュディレクトリの内容を削除します。

PHP
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');

またはWP-CLI経由で実行します。

シェル
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"

次回のフロントエンドリクエスト時に、CSSが自動的に再コンパイルされ、キャッシュされます。

フィルター

blockstudio/tailwind/css

コンパイル前にCSS入力を変更します。CSS入力文字列は@import "tailwindcss";で始まり、その後に任意の設定が続きます。このフィルターを使って、追加のCSSディレクティブ、カスタム@layerルール、プラグインのインポートを追加できます。

PHP
add_filter('blockstudio/tailwind/css', function (string $css): string {
    // Add a custom utility
    $css .= "\n@utility container-narrow { max-width: 48rem; margin-inline: auto; }";

    return $css;
});

コンパイル対象となるCSS入力全体は次のようになります。

CSS
/* Base import */
@import 'tailwindcss';

/* Config from settings (if set) */
@theme {
  --color-brand: pink;
}

/* Anything added via the blockstudio/tailwind/css filter */

出力バッファ

Tailwindのコンパイルは、Blockstudioの出力バッファーシステムと連携します。WordPressのレンダリング完了後にバッファーがページ全体のHTMLを取得するため、Tailwindはブロックテンプレート、テーマテンプレート、プラグインの出力、the_contentフィルター、ウィジェット領域など、あらゆるソースのクラスをスキャンできます。

コンパイルフィルターはblockstudio/buffer/outputフックの優先度999999で実行され、ほかのすべての変更後に最終的なHTMLを処理します。バッファはtemplate_redirectアクションで開始されるため、フロントエンドのリクエストでのみ動作し、管理画面、REST API、AJAXの各コンテキストでは動作しません。

ドキュメント全体のバッファリングによってこれが可能になるため、デフォルトで有効になっています。Tailwindもブロックアセットも使わないサイトでは、無効にできます。

PHP
add_filter( 'blockstudio/buffer/enabled', '__return_false' );

falseを返すとバッファ全体がスキップされ、Tailwindのコンパイルと、ブロックのスタイルおよびスクリプトをheadとfooterに移動する処理も無効になります。

アーキテクチャ

コード
Frontend Request
  │
  ├─ WordPress renders HTML into output buffer
  │
  ├─ blockstudio/buffer/output filter (priority 999999)
  │   │
  │   ├─ Settings::get('tailwind/enabled') → false? Return HTML unchanged
  │   │
  │   ├─ build_css_input()
  │   │   ├─ @import "tailwindcss"
  │   │   ├─ + tailwind/config setting
  │   │   └─ + blockstudio/tailwind/css filter
  │   │
  │   ├─ TailwindPHP::extractCandidates($html)
  │   │   └─ Returns array of CSS class names found in HTML
  │   │
  │   ├─ Cache key = md5(sorted candidates + css input)
  │   │
  │   ├─ Cache hit?
  │   │   ├─ Yes → Read CSS from the shared runtime `tailwind/{hash}.css` scope
  │   │   └─ No  → TailwindPHP::generate() → Write to cache file
  │   │
  │   └─ Inject inline CSS, or link the content-hashed cache file when tailwind.output is "link"
  │
  └─ Browser receives HTML with compiled CSS


Editor Request
  │
  ├─ Admin loads block editor
  │
  ├─ Block with classes field (tailwind: true) detected
  │   └─ Block_Registry::set_tailwind_active(true)
  │
  ├─ Admin passes isTailwindActive + tailwindUrl to JS
  │
  └─ useTailwind() hook
      ├─ Injects Tailwind CDN script into document
      ├─ Creates hidden template div with HTML content
      ├─ Creates style tag for config
      └─ CDN compiles CSS in-browser for live preview

完全な例

カスタムテーマカラーと、それを使用するブロックを含む、完全に動作する設定です。

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; --color-brand-light: #a5b4fc; --color-surface: #f8fafc; } @layer utilities { .section-padding { @apply py-20 px-6; } .content-width { @apply max-w-5xl mx-auto; } .heading-xl { @apply text-4xl font-bold tracking-tight; } }"
  }
}
JSON
{
  "name": "my-theme/hero",
  "title": "Hero Section",
  "blockstudio": {
    "attributes": [
      {
        "id": "title",
        "type": "text",
        "label": "Title",
        "default": "Welcome"
      },
      {
        "id": "wrapperClasses",
        "type": "classes",
        "label": "Wrapper Classes",
        "tailwind": true,
        "default": "section-padding bg-surface"
      },
      {
        "id": "titleClasses",
        "type": "classes",
        "label": "Title Classes",
        "tailwind": true,
        "default": "heading-xl text-brand"
      }
    ]
  }
}
PHP
<section class="<?php echo $a['wrapperClasses']; ?>">
  <div class="content-width">
    <h1 class="<?php echo $a['titleClasses']; ?>">
      <?php echo esc_html($a['title']); ?>
    </h1>
  </div>
</section>

これにより、すべてのTailwindユーティリティとカスタムテーマカラーが1つのインライン<style>タグにコンパイルされ、フロントエンドに出力されます。

ブロックライブラリの構築

本番用テーマのデザイントークン、カスタムユーティリティ、Tailwind v4の完全なセットアップ。