Ga naar de inhoud

Tailwind CSS

Blockstudio bevat ingebouwde ondersteuning voor Tailwind CSS v4. Wanneer deze functie is ingeschakeld, wordt elke frontendpagina server-side gecompileerd via TailwindPHP, met automatische caching op basis van bestanden. In de blokeditor biedt een gebundeld Tailwind CDN-script een live preview terwijl u bewerkt.

Geen buildstap, geen CLI, geen Node.js nodig.

Hoe het werkt

Blockstudio gebruikt twee afzonderlijke compilatiestrategieën, afhankelijk van de context:

Frontend (server-side)

Bij elke frontendaanvraag legt Blockstudio de volledige pagina-HTML vast via een outputbuffer, haalt alle klassekandidaten van CSS eruit, compileert alleen de CSS die daadwerkelijk wordt gebruikt en voegt het resultaat als een inline-tag <style> toe vóór </head>.

De compilatiestroom:

  1. WordPress rendert de volledige pagina-HTML naar een outputbuffer
  2. TailwindPHP::extractCandidates() scant de HTML en haalt alle mogelijke CSS-klassenamen eruit (snelle regex, geen compilatie)
  3. De gesorteerde kandidaten worden samen met de configuratie CSS gehasht om een cachekey te maken
  4. Bij een cachehit wordt de gecompileerde CSS van de schijf gelezen en ingevoegd
  5. Bij een cachemisser compileert TailwindPHP::generate() de CSS, schrijft deze naar de cachemap en voegt deze in

De gecompileerde CSS wordt ingevoegd als:

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

Dit omvat de preflight van Tailwind (reset van CSS) en alle overeenkomende utilityklassen.

Editor (client-side)

In de blokeditor draait client-side een gebundeld Tailwind CDN-script (browserbuild van Tailwind CSS v4). Dit biedt direct een live preview terwijl u klassennamen typt, zonder serveraanvragen. De CDN wordt alleen in de editor geladen en wordt nooit op de frontend geserveerd.

Wanneer assets.reset.enabled actief is, herstelt Blockstudio ook de gangbare display- en positioneringshulpprogramma’s van Tailwind in het editorcanvas. Zo worden wrapperklassen zoals flex, grid, absolute, fixed en sticky niet overschreven door de wrapperregels voor editorblokken van WordPress, waardoor layouts op basis van utilityklassen beter overeenkomen met de frontend.

Tailwind inschakelen

Voeg de configuratie tailwind toe aan uw blockstudio.json:

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

Of schakel het in via een filter:

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

Wanneer enabled is ingesteld op true, wordt voor elke frontendpagina automatisch Tailwind CSS gecompileerd en ingevoegd. U kunt utilityklassen van Tailwind overal gebruiken: in bloktemplates, thematemplates, the_content-filters of in elk HTML dat in de pagina-uitvoer voorkomt.

Frontenduitvoer

Gecompileerde CSS wordt standaard inline ingevoegd, zodat de uitvoer van eerdere versies behouden blijft. Sites met veel gedeelde regels kunnen in plaats daarvan kiezen voor een stylesheet met een contenthash:

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

"output": "link" geeft het bestaande cachebestand tailwind/{content-hash}.css uit als <link rel="stylesheet">. De URL verandert wanneer de runtime-identiteit, kandidaten, engine of invoer CSS verandert, zodat browsers en edge-caches oude URL’s veilig kunnen bewaren. Configureer de webserver of CDN om voor deze cachescope een lang geldige header Cache-Control: public, immutable te versturen.

De standaardcachemap is openbaar toegankelijk onder wp-content. Als cache.path naar een privévolume met een absoluut pad verwijst, valt Blockstudio terug op inline CSS, tenzij het bestaande filter blockstudio/files/url een openbare URL voor de scope tailwind aanlevert:

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

Helpers voor templatecompositie

Blockstudio biedt templates van PHP dezelfde gebundelde engine TailwindPHP. Een kopie in het thema of een fallbackimplementatie is niet nodig:

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() accepteert geneste klassewaarden en lost conflicterende Tailwind-hulpprogramma’s op. bs_tw_variants() retourneert een aanroepbare functie in CVA-stijl die base, varianten, standaardvarianten, samengestelde varianten, class en className ondersteunt.

Configuratie

Tailwind v4 gebruikt een configuratieaanpak waarbij CSS centraal staat. In plaats van een configuratiebestand voor JavaScript te gebruiken, schrijft u de configuratie rechtstreeks als CSS met de directive @theme.

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

De waarde config is een tekenreeks voor CSS die achter de directive @import "tailwindcss" wordt toegevoegd. U kunt hier elke geldige syntaxis voor Tailwind v4 CSS gebruiken:

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

Voor configuraties over meerdere regels is de filteraanpak prettiger:

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

Aangepaste utilityklassen

Gebruik @layer utilities met de directive @apply van Tailwind rechtstreeks in uw configuratiereeks om herbruikbare aliassen voor klassen te definiëren:

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

Dit compileert deze klassen samen met alle standaardhulpprogramma’s van Tailwind. Ze werken zowel aan de voorkant (compilatie aan de serverzijde) als in de editor (CDN-voorbeeld).

Blockstudio behoudt de canonieke volgorde van cascadelagen van Tailwind: theme, base, components en vervolgens utilities. Dit komt overeen met Tailwind CSS, zodat regels in latere lagen eerdere lagen zoals verwacht kunnen overschrijven.

Type van het veld Classes

Stel tailwind: true in op het veld om Tailwind-klassen te gebruiken in het veld classes van een blok, met ondersteuning voor automatisch aanvullen:

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

Wanneer tailwind true is:

  • Het veld geeft suggesties voor automatisch aanvullen uit de volledige klassenlijst van Tailwind
  • Het script Tailwind CDN wordt in de editor geladen voor een livevoorbeeld
  • Klassen worden als een door spaties gescheiden tekenreeks opgeslagen in de blokattributen

Gebruik de waarde van classes in uw template:

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

Referentie voor instellingen

Optie Type Standaard Beschrijving
enabled boolean false Compilatie van Tailwind CSS aan de voorkant inschakelen
config string "" Configuratiereeks met Tailwind v4 CSS als uitgangspunt

Instellen via JSON

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

Instellen via filters

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

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

Caching

Blockstudio gebruikt een aangepaste cachingstrategie die is ontworpen voor de utilitygebaseerde architectuur van Tailwind.

Hoe de cache werkt

In plaats van de volledige pagina-HTML te hashen (waardoor de cache bij elk verzoek ongeldig zou worden door nonces, tijdstempels en andere dynamische inhoud), haalt Blockstudio alleen de klassekandidaten van CSS uit HTML. Deze kandidaten worden gesorteerd en samen met de configuratie van CSS gehasht om een stabiele cachesleutel te maken.

Dit betekent:

  • Twee pagina’s met dezelfde verzameling Tailwind-klassen delen hetzelfde gecachte CSS-bestand, zelfs als hun HTML volledig verschilt
  • Dynamische inhoud zoals nonces, balken voor ingelogde gebruikers, aantallen reacties en tijdstempels maakt de cache niet ongeldig
  • De cache wordt alleen ongeldig wanneer de verzameling CSS-klassen op een pagina verandert of de configuratie van Tailwind wijzigt

Wanneer een runtime een logische ontdekkingsbron gebruikt, maken ook de geselecteerde bron en de runtimecontext deel uit van de cachenaamruimte. De laatst goede CSS is geïsoleerd tussen voorbeelden en kan niet van de ene bronselectie naar de andere lekken.

Cachelocatie

Cachebestanden worden opgeslagen in:

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

De geconfigureerde cache.path, de huidige multisite-identiteit en de volledige runtime-identiteit bepalen het exacte voorvoegsel. Elk bestand krijgt een naam met een MD5-hash: {hash}.css.

De cache wissen

Verwijder de inhoud van de cachemap om opnieuw compileren af te dwingen:

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

Of via WP-CLI:

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

Bij het volgende frontendverzoek worden CSS automatisch opnieuw gecompileerd en in de cache opgeslagen.

Filters

blockstudio/tailwind/css

Wijzig de invoer van CSS vóór de compilatie. De invoertekenreeks van CSS begint met @import "tailwindcss";, gevolgd door een willekeurige configuratie. Gebruik dit filter om extra directives van CSS, aangepaste @layer-regels of pluginimports toe te voegen.

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

De volledige invoer van CSS die wordt gecompileerd, ziet er zo uit:

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

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

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

Uitvoerbuffer

De compilatie van Tailwind haakt in op het uitvoerbuffersysteem van Blockstudio. De buffer legt de volledige pagina-HTML vast nadat WordPress klaar is met renderen, zodat Tailwind alle klassen uit elke bron kan scannen: bloktemplates, thematemplates, pluginuitvoer, the_content-filters en widgetgebieden.

Het compilatiefilter wordt uitgevoerd met prioriteit 999999 op de hook blockstudio/buffer/output, zodat het de uiteindelijke HTML verwerkt nadat alle andere wijzigingen zijn aangebracht. De buffer wordt gestart bij de actie template_redirect, wat betekent dat deze alleen wordt uitgevoerd bij frontendverzoeken, niet in de beheeromgeving, REST API of AJAX-contexten.

Door het hele document te bufferen, wordt dit mogelijk. Daarom is dit standaard ingeschakeld. Een site die noch Tailwind noch blokassets gebruikt, kan dit uitschakelen:

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

Als u false retourneert, wordt de buffer volledig overgeslagen. Ook worden dan de compilatie van Tailwind en het verplaatsen van blokstijlen en -scripts naar de head en footer uitgeschakeld.

Architectuur

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

Volledig voorbeeld

Een complete, werkende configuratie met aangepaste themakleuren en een blok dat deze gebruikt:

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>

Dit wordt aan de voorkant weergegeven met alle Tailwind-hulpprogramma’s en aangepaste themakleuren gecompileerd in één inline <style>-tag.

Een blokbibliotheek bouwen

Ontwerptokens, aangepaste hulpprogramma’s en de complete configuratie van Tailwind v4 voor een productiethema.