Zum Inhalt springen

Tailwind CSS

Blockstudio bietet integrierte Unterstützung für Tailwind CSS v4. Ist die Funktion aktiviert, wird jede Frontend-Seite serverseitig über TailwindPHP kompiliert und automatisch dateibasiert zwischengespeichert. Im Block-Editor ermöglicht ein gebündeltes Tailwind-CDN-Skript eine Live-Vorschau während der Bearbeitung.

Kein Build-Schritt, kein CLI, kein Node.js erforderlich.

So funktioniert es

Blockstudio verwendet je nach Kontext zwei getrennte Kompilierungsverfahren:

Frontend (serverseitig)

Bei jeder Frontend-Anfrage erfasst Blockstudio den vollständigen Seiten-HTML in einem Ausgabepuffer, extrahiert alle CSS-Klassenkandidaten, kompiliert nur die tatsächlich verwendeten CSS und fügt das Ergebnis als Inline-<style>-Tag vor </head> ein.

Der Kompilierungsablauf:

  1. WordPress rendert den vollständigen Seiten-HTML in einen Ausgabepuffer
  2. TailwindPHP::extractCandidates() durchsucht das HTML und extrahiert alle möglichen CSS-Klassennamen (schneller Regex, keine Kompilierung)
  3. Die sortierten Kandidaten werden gemeinsam mit der CSS-Konfiguration gehasht, um einen Cache-Schlüssel zu erstellen
  4. Bei einem Cache-Treffer wird das kompilierte CSS von der Festplatte gelesen und eingefügt
  5. Bei einem Cache-Miss kompiliert TailwindPHP::generate() das CSS, schreibt es in das Cache-Verzeichnis und fügt es ein

Das kompilierte CSS wird wie folgt eingefügt:

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

Dazu gehören Tailwinds Preflight (CSS-Reset) und alle passenden Utility-Klassen.

Editor (clientseitig)

Im Block-Editor läuft ein gebündeltes Tailwind-CDN-Skript (Browser-Build von Tailwind CSS v4) clientseitig. So gibt es beim Eingeben von Klassennamen sofort eine Live-Vorschau, ganz ohne Serveranfragen. Das CDN wird nur im Editor geladen und niemals im Frontend ausgeliefert.

Wenn assets.reset.enabled aktiv ist, stellt Blockstudio im Editor-Canvas auch Tailwinds gängige Anzeige- und Positionierungs-Utilities wieder her. So werden Wrapper-Klassen wie flex, grid, absolute, fixed und sticky nicht von den Editor-Block-Wrapper-Regeln von WordPress überschrieben. Dadurch entsprechen Utility-gesteuerte Layouts dem Frontend genauer.

Tailwind aktivieren

Füge die tailwind-Konfiguration zu deiner blockstudio.json hinzu:

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

Oder aktiviere es über einen Filter:

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

Wenn enabled auf true gesetzt ist, wird Tailwind CSS automatisch für jede Frontend-Seite kompiliert und eingefügt. Du kannst Tailwind-Utility-Klassen überall verwenden: in Block-Templates, Theme-Templates, the_content-Filtern oder jedem HTML, das in der Seitenausgabe erscheint.

Frontend-Ausgabe

Kompiliertes CSS wird standardmäßig inline eingefügt und erhält so die Ausgabe früherer Versionen. Websites mit vielen gemeinsam genutzten Regeln können stattdessen ein Stylesheet mit Inhalts-Hash verwenden:

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

"output": "link" gibt die vorhandene tailwind/{content-hash}.css-Cache-Datei als <link rel="stylesheet"> aus. URL ändert sich, wenn sich die Laufzeitidentität, Kandidaten, Engine oder CSS-Eingabe ändern. So können Browser und Edge-Caches alte URLs sicher beibehalten. Konfiguriere den Webserver oder CDN so, dass ein langlebiger Cache-Control: public, immutable-Header für diesen Cache-Bereich gesendet wird.

Das Standard-Cache-Stammverzeichnis liegt öffentlich unter wp-content. Wenn cache.path auf ein privates absolutes Volume verweist, greift Blockstudio auf Inline-CSS zurück, sofern der vorhandene blockstudio/files/url-Filter keinen öffentlichen URL für den Bereich tailwind bereitstellt:

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
);

Hilfsfunktionen für die Template-Komposition

Blockstudio stellt dieselbe gebündelte TailwindPHP-Engine für PHP-Templates bereit. Eine Kopie oder Fallback-Implementierung im Theme ist nicht erforderlich:

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() akzeptiert verschachtelte Klassenwerte und löst Konflikte zwischen Tailwind-Utilities auf. bs_tw_variants() gibt eine aufrufbare Funktion im CVA-Stil zurück, die Basisklassen, Varianten, Standardvarianten, kombinierte Varianten, class und className unterstützt.

Konfiguration

Tailwind v4 verwendet einen Konfigurationsansatz, bei dem CSS im Vordergrund steht. Statt einer JavaScript-Konfigurationsdatei schreibst du die Konfiguration direkt als CSS mit der Direktive @theme.

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

Der Wert config ist ein CSS-String, der nach der Direktive @import "tailwindcss" angefügt wird. Hier kannst du jede gültige Syntax für Tailwind v4 CSS verwenden:

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

Bei mehrzeiligen Konfigurationen ist der Filteransatz komfortabler:

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;
});

Benutzerdefinierte Utility-Klassen

Um wiederverwendbare Klassenaliase zu definieren, verwende @layer utilities direkt mit Tailwinds Direktive @apply in deinem Konfigurationsstring:

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; } }"
  }
}

Dadurch werden diese Klassen zusammen mit allen standardmäßigen Tailwind-Utilities kompiliert. Sie funktionieren sowohl im Frontend (serverseitige Kompilierung) als auch im Editor (CDN-Vorschau).

Blockstudio erhält Tailwinds kanonische Reihenfolge der Kaskadenschichten: theme, base, components und dann utilities. Das entspricht Tailwind CSS, sodass Regeln in späteren Schichten frühere wie erwartet überschreiben können.

Feldtyp „Classes“

Damit du Tailwind-Klassen im classes-Feld eines Blocks mit Autovervollständigung verwenden kannst, setze tailwind: true für das Feld:

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

Wenn tailwind auf true gesetzt ist:

  • Das Feld bietet Autovervollständigungsvorschläge aus der vollständigen Tailwind-Klassenliste.
  • Das Tailwind-CDN-Skript wird für die Live-Vorschau im Editor geladen.
  • Klassen werden als durch Leerzeichen getrennter String in den Blockattributen gespeichert.

Verwende den Klassenwert in deinem Template:

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

Einstellungsreferenz

Option Typ Standard Beschreibung
enabled boolean false Tailwind CSS-Kompilierung im Frontend aktivieren
config string "" Konfigurationsstring für Tailwind v4 mit CSS an erster Stelle

Über JSON festlegen

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

Über Filter festlegen

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

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

Caching

Blockstudio verwendet eine benutzerdefinierte Caching-Strategie für Tailwinds Utility-basierte Architektur.

Funktionsweise des Caches

Statt den gesamten Seiten-HTML zu hashen (wodurch der Cache wegen Nonces, Zeitstempeln und anderen dynamischen Inhalten bei jeder Anfrage ungültig würde), extrahiert Blockstudio nur die CSS-Klassenkandidaten aus HTML. Diese Kandidaten werden sortiert und gemeinsam mit der CSS-Konfiguration gehasht, um einen stabilen Cache-Schlüssel zu erzeugen.

Das bedeutet:

  • Zwei Seiten, die dieselbe Menge an Tailwind-Klassen verwenden, teilen sich dieselbe zwischengespeicherte CSS-Datei, auch wenn ihr HTML völlig unterschiedlich ist
  • Dynamische Inhalte wie Nonces, Leisten für angemeldete Benutzer, Kommentaranzahlen und Zeitstempel umgehen den Cache nicht
  • Der Cache wird nur ungültig, wenn sich die Menge der CSS-Klassen auf einer Seite oder die Tailwind-Konfiguration ändert

Wenn eine Laufzeit eine logische Erkennungsquelle verwendet, fließen auch die ausgewählte Quelle und der Laufzeitkontext in den Cache-Namensraum ein. Zuletzt erfolgreiche CSS werden zwischen Vorschauen isoliert und können nicht von einer Quellenauswahl in eine andere gelangen.

Cache-Speicherort

Cache-Dateien werden hier gespeichert:

Code
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

Das konfigurierte cache.path, die aktuelle Multisite-Identität und die vollständige Laufzeitidentität bestimmen das genaue Präfix. Jede Datei erhält einen MD5-Hash als Namen: {hash}.css.

Cache leeren

Lösche den Inhalt des Cache-Verzeichnisses, um eine Neukompilierung zu erzwingen:

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

Oder über WP-CLI:

Shell
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"

Die nächste Frontend-Anfrage kompiliert die CSS automatisch neu und legt sie im Cache ab.

Filter

blockstudio/tailwind/css

Ändere die CSS-Eingabe vor der Kompilierung. Die CSS-Eingabezeichenfolge beginnt mit @import "tailwindcss";, gefolgt von beliebiger Konfiguration. Verwende diesen Filter, um zusätzliche CSS-Direktiven, benutzerdefinierte @layer-Regeln oder Plugin-Imports hinzuzufügen.

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;
});

Die vollständige CSS-Eingabe, die kompiliert wird, sieht so aus:

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

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

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

Ausgabepuffer

Die Tailwind-Kompilierung ist in das Ausgabepuffersystem von Blockstudio eingebunden. Der Puffer erfasst das vollständige HTML der Seite, nachdem WordPress das Rendering abgeschlossen hat. So kann Tailwind alle Klassen aus sämtlichen Quellen erfassen: Blockvorlagen, Theme-Vorlagen, Plugin-Ausgabe, the_content-Filter und Widget-Bereiche.

Der Kompilierungsfilter wird mit Priorität 999999 am blockstudio/buffer/output-Hook ausgeführt und verarbeitet dadurch das endgültige HTML nach allen anderen Änderungen. Der Puffer wird bei der Aktion template_redirect gestartet und läuft daher nur bei Frontend-Anfragen, nicht im Adminbereich, in REST API oder in AJAX-Kontexten.

Die Pufferung des gesamten Dokuments macht dies möglich und ist deshalb standardmäßig aktiviert. Eine Website, die weder Tailwind noch Block-Assets verwendet, kann sie deaktivieren:

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

Die Rückgabe von false überspringt den Puffer vollständig und deaktiviert damit auch die Tailwind-Kompilierung sowie das Verschieben von Blockstilen und -skripten in den Head und Footer.

Architektur

Code
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

Vollständiges Beispiel

Ein vollständiges, funktionsfähiges Setup mit benutzerdefinierten Theme-Farben und einem Block, der sie verwendet:

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>

Im Frontend werden dann alle Tailwind-Utilities und benutzerdefinierten Theme-Farben in einem einzigen Inline-<style>-Tag ausgegeben.

Eine Blockbibliothek erstellen

Design-Tokens, benutzerdefinierte Hilfsklassen und die vollständige Einrichtung von Tailwind v4 für ein produktionsreifes Theme.