Vai al contenuto

Tailwind CSS

Blockstudio include il supporto integrato per Tailwind CSS v4. Quando è attivo, ogni pagina frontend viene compilata lato server tramite TailwindPHP con caching automatico basato su file. Nell’editor a blocchi, uno script CDN Tailwind incluso nel bundle offre un’anteprima dal vivo mentre si modifica.

Nessuna fase di build, nessun CLI, nessun Node.js richiesti.

Come funziona

Blockstudio usa due strategie di compilazione distinte a seconda del contesto:

Frontend (lato server)

A ogni richiesta frontend, Blockstudio acquisisce l’intero HTML della pagina tramite un buffer di output, estrae tutti i possibili nomi di classe CSS, compila solo il CSS effettivamente utilizzato e inserisce il risultato come tag <style> inline prima di </head>.

Flusso di compilazione:

  1. WordPress renderizza l’intero HTML della pagina in un buffer di output
  2. TailwindPHP::extractCandidates() analizza il HTML ed estrae tutti i possibili nomi di classe CSS (regex rapida, senza compilazione)
  3. I candidati ordinati vengono sottoposti a hash insieme alla configurazione CSS per creare una chiave cache
  4. In caso di cache hit: il CSS compilato viene letto dal disco e inserito
  5. In caso di cache miss: TailwindPHP::generate() compila il CSS, lo scrive nella directory cache e lo inserisce

Il CSS compilato viene inserito così:

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

Include il preflight di Tailwind (reset CSS) e tutte le classi utility corrispondenti.

Editor (lato client)

Nell’editor a blocchi, uno script Tailwind CDN incluso nel bundle (build browser di Tailwind CSS v4) viene eseguito lato client. Offre un’anteprima dal vivo istantanea mentre digitate i nomi delle classi, senza alcun viaggio di andata e ritorno verso il server. L’CDN viene caricato solo nell’editor e non viene mai servito sul frontend.

Quando assets.reset.enabled è attivo, Blockstudio ripristina anche le comuni utility di visualizzazione e posizionamento di Tailwind nell’area canvas dell’editor. In questo modo, le classi a livello di wrapper come flex, grid, absolute, fixed e sticky non vengono sovrascritte dalle regole del wrapper dei blocchi dell’editor WordPress, così i layout basati sulle utility corrispondono meglio al frontend.

Attivare Tailwind

Aggiungete la configurazione tailwind al vostro blockstudio.json:

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

Oppure attivatelo tramite un filtro:

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

Quando enabled è true, ogni pagina frontend avrà Tailwind CSS compilato e inserito automaticamente. Potete usare le classi utility Tailwind ovunque: nei template dei blocchi, nei template del tema, nei filtri the_content o in qualsiasi HTML presente nell’output della pagina.

Output frontend

Per impostazione predefinita, il CSS compilato è inline e mantiene l’output delle versioni precedenti. I siti con molte regole condivise possono optare invece per un foglio di stile con hash del contenuto:

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

"output": "link" emette il file cache tailwind/{content-hash}.css esistente come <link rel="stylesheet">. L’URL cambia quando cambiano l’identità del runtime, i candidati, il motore o l’input CSS, così browser e cache edge possono conservare in sicurezza i vecchi URL. Configurate il server web o CDN in modo da inviare un’intestazione Cache-Control: public, immutable con durata lunga per questo ambito della cache.

Per impostazione predefinita, la radice della cache è pubblica sotto wp-content. Se cache.path punta a un volume assoluto privato, Blockstudio ripiega su CSS inline, a meno che il filtro blockstudio/files/url esistente non fornisca un URL pubblico per l’ambito tailwind:

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

Helper per la composizione dei template

Blockstudio espone lo stesso motore TailwindPHP incluso nel bundle ai template PHP. Non è necessaria una copia nel tema né un’implementazione di fallback:

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() accetta valori di classe annidati e risolve i conflitti tra le utility Tailwind. bs_tw_variants() restituisce una funzione richiamabile in stile CVA che supporta base, varianti, varianti predefinite, varianti composte, class e className.

Configurazione

Tailwind v4 adotta un approccio di configurazione basato prima su CSS. Invece di un file di configurazione JavaScript, scrivete la configurazione direttamente come CSS usando la direttiva @theme.

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

Il valore config è una stringa CSS che viene aggiunta dopo la direttiva @import "tailwindcss". Qui potete usare qualsiasi sintassi valida di 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); } }"
  }
}

Per configurazioni su più righe, l’approccio con filtro è più pratico:

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

Classi utility personalizzate

Per definire alias di classe riutilizzabili, usate @layer utilities direttamente nella stringa di configurazione con la direttiva @apply di Tailwind:

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

Questo compila queste classi insieme a tutte le utility standard di Tailwind. Funzionano sia nel frontend (compilazione lato server) sia nell’editor (anteprima di CDN).

Blockstudio mantiene l’ordine canonico dei livelli di cascata di Tailwind: theme, base, components, quindi utilities. Corrisponde a Tailwind CSS, perciò le regole nei livelli successivi possono sovrascrivere quelli precedenti come previsto.

Tipo del campo Classes

Per usare le classi Tailwind nel campo classes di un blocco con il completamento automatico, impostate tailwind: true nel campo:

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

Quando tailwind è true:

  • Il campo propone suggerimenti di completamento automatico dall’elenco completo delle classi Tailwind
  • Lo script Tailwind CDN viene caricato nell’editor per l’anteprima in tempo reale
  • Le classi vengono memorizzate come stringa separata da spazi negli attributi del blocco

Usate il valore delle classi nel vostro template:

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

Riferimento delle impostazioni

Opzione Tipo Predefinito Descrizione
enabled boolean false Abilita la compilazione di Tailwind CSS nel frontend
config string "" Stringa di configurazione basata prima su Tailwind v4 CSS

Impostazione tramite JSON

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

Impostazione tramite filtri

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

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

Memorizzazione nella cache

Blockstudio usa una strategia di memorizzazione nella cache personalizzata, progettata per l’architettura basata su utility di Tailwind.

Funzionamento della cache

Invece di calcolare l’hash dell’intero HTML della pagina (il che invaliderebbe la cache a ogni richiesta a causa di nonce, timestamp e altri contenuti dinamici), Blockstudio estrae solo i candidati di classe CSS da HTML. Questi candidati vengono ordinati e sottoposti a hash insieme alla configurazione CSS per generare una chiave di cache stabile.

Questo significa che:

  • Due pagine che usano lo stesso insieme di classi Tailwind condividono lo stesso file CSS memorizzato nella cache, anche se il loro HTML è completamente diverso
  • I contenuti dinamici come nonce, barre degli utenti connessi, conteggi dei commenti e timestamp non invalidano la cache
  • La cache viene invalidata solo quando cambia l’insieme di classi CSS in una pagina o cambia la configurazione Tailwind

Quando un runtime usa una fonte di rilevamento logico, anche la fonte selezionata e il contesto del runtime contribuiscono allo spazio dei nomi della cache. L’ultimo CSS valido è isolato tra le anteprime e non può propagarsi da una selezione della fonte a un’altra.

Posizione della cache

I file della cache sono archiviati in:

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

Il cache.path configurato, l’identità multisito corrente e l’identità completa del runtime determinano il prefisso esatto. Ogni file è denominato con un hash MD5: {hash}.css.

Svuotare la cache

Eliminate il contenuto della directory della cache per forzare la ricompilazione:

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

Oppure tramite WP-CLI:

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

La prossima richiesta dal frontend ricompilerà e memorizzerà automaticamente nella cache CSS.

Filtri

blockstudio/tailwind/css

Modificate l’input CSS prima della compilazione. La stringa di input CSS inizia con @import "tailwindcss";, seguita da qualsiasi configurazione. Usate questo filtro per aggiungere direttive CSS, regole @layer personalizzate o importazioni di plugin.

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

L’input CSS completo che viene compilato è così:

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

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

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

Buffer di output

La compilazione di Tailwind si integra con il sistema di buffer di output di Blockstudio. Il buffer acquisisce l’intero HTML della pagina dopo che WordPress ha terminato il rendering, consentendo a Tailwind di esaminare tutte le classi provenienti da ogni fonte: template dei blocchi e del tema, output dei plugin, filtri the_content e aree dei widget.

Il filtro di compilazione viene eseguito con priorità 999999 sull’hook blockstudio/buffer/output, così elabora il risultato HTML finale dopo tutte le altre modifiche. Il buffer viene avviato sull’azione template_redirect, quindi viene eseguito solo sulle richieste del frontend, non nell’amministrazione, in REST API o nei contesti AJAX.

Il buffering dell’intero documento rende possibile tutto questo, quindi è attivo per impostazione predefinita. Un sito che non usa né Tailwind né risorse dei blocchi può disattivarlo:

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

Restituendo false si salta del tutto il buffer, disattivando anche la compilazione di Tailwind e lo spostamento degli stili e degli script dei blocchi nell’head e nel footer.

Architettura

Codice
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

Esempio completo

Configurazione completa e funzionante con colori personalizzati per il tema e un blocco che li usa:

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>

Nel frontend viene generato un unico tag <style> inline con tutte le utility Tailwind e i colori personalizzati del tema compilati.

Creare una libreria di blocchi

Token di design, utility personalizzate e configurazione completa di Tailwind v4 per un tema pronto per la produzione.