Tailwind CSS
Blockstudio intègre la prise en charge de Tailwind CSS v4. Lorsqu’elle est activée, chaque page publique est compilée côté serveur via TailwindPHP, avec une mise en cache automatique basée sur des fichiers. Dans l’éditeur de blocs, un script Tailwind CDN intégré fournit un aperçu en direct pendant la modification.
Aucune étape de compilation, aucun CLI, aucun Node.js requis.
Fonctionnement
Blockstudio utilise deux stratégies de compilation distinctes selon le contexte :
Frontend (côté serveur)
À chaque requête publique, Blockstudio capture l’intégralité du HTML de la page dans un tampon de sortie, extrait toutes les classes candidates CSS, ne compile que les CSS réellement utilisées et injecte le résultat dans une balise <style> intégrée avant </head>.
Le processus de compilation :
- WordPress génère le HTML complet de la page dans un tampon de sortie
TailwindPHP::extractCandidates()analyse le HTML et extrait tous les noms de classes CSS possibles (expression rationnelle rapide, sans compilation)- Les candidats triés sont hachés avec la configuration CSS pour créer une clé de cache
- En cas de succès du cache : le CSS compilé est lu sur le disque et injecté
- En cas d’absence dans le cache :
TailwindPHP::generate()compile le CSS, l’écrit dans le répertoire de cache et l’injecte
Le CSS compilé est injecté ainsi :
<style id="blockstudio-tailwind">
/* compiled CSS */
</style>
Cela inclut le prétraitement de Tailwind (réinitialisation CSS) et toutes les classes utilitaires correspondantes.
Éditeur (côté client)
Dans l’éditeur de blocs, un script Tailwind CDN intégré (version navigateur de Tailwind CSS v4) s’exécute côté client. Il fournit un aperçu instantané en direct à mesure que vous saisissez des noms de classes, sans aller-retour vers le serveur. Le CDN est chargé uniquement dans l’éditeur et n’est jamais servi sur le frontend.
Lorsque assets.reset.enabled est actif, Blockstudio rétablit également les utilitaires courants d’affichage et de positionnement de Tailwind dans le canevas de l’éditeur. Les classes au niveau de l’élément englobant, telles que flex, grid, absolute, fixed et sticky, ne sont ainsi pas remplacées par les règles des éléments englobants des blocs de l’éditeur WordPress, ce qui rapproche les mises en page basées sur les utilitaires du frontend.
Activer Tailwind
Ajoutez la configuration tailwind à votre blockstudio.json :
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
Vous pouvez également l’activer avec un filtre :
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
Lorsque enabled est true, le Tailwind CSS est automatiquement compilé et injecté sur chaque page publique. Vous pouvez utiliser les classes utilitaires Tailwind partout : dans les modèles de blocs, les modèles de thème, les filtres the_content ou tout HTML présent dans le code source de la page.
Sortie frontend
Le CSS compilé est intégré par défaut, afin de préserver la sortie utilisée par les versions précédentes. Les sites comportant de nombreuses règles partagées peuvent choisir à la place une feuille de style dont le nom est haché d’après son contenu :
{
"tailwind": {
"enabled": true,
"output": "link"
}
}
"output": "link" émet le fichier de cache tailwind/{content-hash}.css existant sous forme de <link rel="stylesheet">. Le URL change lorsque l’identité d’exécution, les candidats, le moteur ou l’entrée CSS changent, afin que les navigateurs et les caches en périphérie puissent conserver sans risque les anciennes URL. Configurez le serveur Web ou CDN pour envoyer un en-tête Cache-Control: public, immutable de longue durée pour cet espace de cache.
La racine de cache par défaut est publique et se trouve sous wp-content. Si cache.path pointe vers un volume absolu privé, Blockstudio utilise une solution de repli avec CSS intégré, à moins que le filtre blockstudio/files/url existant ne fournisse un URL public pour l’espace tailwind :
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
);
Fonctions d’aide à la composition des modèles
Blockstudio expose le même moteur TailwindPHP intégré aux modèles PHP. Aucune copie dans le thème ni implémentation de remplacement n’est nécessaire :
$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() accepte les valeurs de classe imbriquées et résout les conflits entre les utilitaires Tailwind. bs_tw_variants() renvoie une fonction appelable de type CVA prenant en charge une base, des variantes, des variantes par défaut, des variantes composées, class et className.
Configuration
Tailwind v4 adopte une approche de configuration axée sur CSS. Au lieu d’un fichier de configuration JavaScript, vous écrivez directement la configuration sous forme de CSS à l’aide de la directive @theme.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
La valeur config est une chaîne CSS ajoutée après la directive @import "tailwindcss". Vous pouvez y utiliser toute syntaxe Tailwind v4 CSS valide :
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
Pour les configurations multilignes, l’approche par filtre est plus pratique :
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;
});
Classes utilitaires personnalisées
Pour définir des alias de classe réutilisables, utilisez @layer utilities avec la directive @apply de Tailwind directement dans votre chaîne de configuration :
{
"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; } }"
}
}
Cela compile ces classes avec tous les utilitaires Tailwind standard. Elles fonctionnent à la fois sur le site (compilation côté serveur) et dans l’éditeur (aperçu CDN).
Blockstudio préserve l’ordre canonique des couches de cascade de Tailwind :
theme, base, components, puis utilities. Cela correspond à Tailwind CSS, de sorte que
les règles des couches ultérieures peuvent remplacer celles des couches précédentes, comme prévu.
Type de champ Classes
Pour utiliser les classes Tailwind dans un champ classes d’un bloc avec la saisie semi-automatique, définissez tailwind: true sur le champ :
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{
"id": "classes",
"type": "classes",
"label": "Classes",
"tailwind": true,
"default": "bg-white text-gray-900"
}
]
}
}
Lorsque tailwind est true :
- Le champ propose des suggestions de saisie semi-automatique à partir de la liste complète des classes Tailwind
- Le script Tailwind CDN est chargé dans l’éditeur pour afficher un aperçu en direct
- Les classes sont stockées sous forme de chaîne séparée par des espaces dans les attributs du bloc
Utilisez la valeur des classes dans votre modèle :
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
Référence des réglages
| Option | Type | Par défaut | Description |
|---|---|---|---|
enabled |
boolean | false |
Activer la compilation Tailwind CSS sur le site |
config |
string | "" |
Chaîne de configuration Tailwind v4 axée sur CSS |
Réglage via JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
Réglage via des filtres
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
add_filter('blockstudio/settings/tailwind/config', function () {
return '@theme { --color-brand: pink; }';
});
Mise en cache
Blockstudio utilise une stratégie de mise en cache personnalisée, conçue pour l’architecture fondée sur les utilitaires de Tailwind.
Fonctionnement du cache
Plutôt que de hacher le HTML de toute la page (ce qui invaliderait le cache à chaque requête à cause des nonces, des horodatages et d’autres contenus dynamiques), Blockstudio extrait uniquement les classes candidates CSS du HTML. Ces candidates sont triées, puis hachées avec la configuration CSS pour produire une clé de cache stable.
Cela signifie que :
- Deux pages utilisant le même ensemble de classes Tailwind partagent le même fichier CSS en cache, même si leur HTML est complètement différent
- Le contenu dynamique, comme les nonces, les barres des utilisateurs connectés, le nombre de commentaires et les horodatages, n’invalide pas le cache
- Le cache n’est invalidé que si l’ensemble des classes CSS d’une page ou la configuration Tailwind change
Lorsqu’un environnement d’exécution utilise une source de découverte logique, la source sélectionnée et le contexte d’exécution font également partie de l’espace de noms du cache. Les résultats CSS les plus récents considérés comme valides sont isolés entre les aperçus et ne peuvent pas être transmis d’une sélection de source à une autre.
Emplacement du cache
Les fichiers de cache sont stockés dans :
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
Le cache.path configuré, l’identité multisite actuelle et l’identité complète de l’environnement d’exécution déterminent le préfixe exact. Chaque fichier porte un nom contenant un hachage MD5 :
{hash}.css.
Vider le cache
Supprimez le contenu du répertoire de cache pour forcer la recompilation :
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
Ou via WP-CLI :
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
La prochaine requête sur le site recompilera automatiquement CSS et le mettra en cache.
Filtres
blockstudio/tailwind/css
Modifiez l’entrée CSS avant la compilation. La chaîne d’entrée CSS commence par @import "tailwindcss";, suivie de n’importe quelle configuration. Utilisez ce filtre pour ajouter des directives CSS supplémentaires, des règles @layer personnalisées ou des imports de plugins.
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;
});
Voici à quoi ressemble l’entrée complète CSS compilée :
/* Base import */
@import 'tailwindcss';
/* Config from settings (if set) */
@theme {
--color-brand: pink;
}
/* Anything added via the blockstudio/tailwind/css filter */
Tampon de sortie
La compilation Tailwind s’intègre au système de tampon de sortie de Blockstudio. Le tampon capture le HTML complet de la page une fois que WordPress a terminé le rendu, ce qui permet à Tailwind d’analyser toutes les classes provenant de chaque source : modèles de blocs, modèles de thème, sortie de plugins, filtres the_content et zones de widgets.
Le filtre de compilation s’exécute à la priorité 999999 sur le hook blockstudio/buffer/output afin de traiter le HTML final après toutes les autres modifications. Le tampon est démarré lors de l’action template_redirect, ce qui signifie qu’il ne s’exécute que pour les requêtes du site, et non dans l’administration, REST API ou les contextes AJAX.
La mise en tampon de tout le document rend cela possible ; elle est donc activée par défaut. Un site qui n’utilise ni Tailwind ni les ressources des blocs peut la désactiver :
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
Renvoyer false ignore entièrement le tampon, ce qui désactive également la compilation Tailwind ainsi que le déplacement des styles et des scripts des blocs vers l’en-tête et le pied de page.
Architecture
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
Exemple complet
Configuration complète fonctionnelle avec des couleurs de thème personnalisées et un bloc qui les utilise :
{
"$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; } }"
}
}
{
"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"
}
]
}
}
<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>
Sur le site, cela génère toutes les classes utilitaires Tailwind et les couleurs de thème personnalisées compilées dans une seule balise <style> intégrée.
Créer une bibliothèque de blocs
Jetons de conception, utilitaires personnalisés et configuration Tailwind v4 complète pour un thème prêt à la production.