Saltar al contenido

Tailwind CSS

Blockstudio incluye compatibilidad integrada con Tailwind CSS v4. Al activarla, cada página del frontend se compila en el servidor mediante TailwindPHP con almacenamiento automático en caché basado en archivos. En el editor de bloques, un script Tailwind CDN incluido ofrece una vista previa en directo mientras edita.

Sin pasos de compilación, sin CLI y sin necesidad de Node.js.

Cómo funciona

Blockstudio utiliza dos estrategias de compilación distintas según el contexto:

Frontend (lado del servidor)

En cada solicitud al frontend, Blockstudio captura el HTML completo de la página en un búfer de salida, extrae todos los candidatos de clase CSS, compila solo el CSS que se utiliza realmente e inyecta el resultado como una etiqueta <style> en línea antes de </head>.

El flujo de compilación:

  1. WordPress renderiza el HTML completo de la página en un búfer de salida
  2. TailwindPHP::extractCandidates() analiza el HTML y extrae todos los posibles nombres de clase CSS (expresión regular rápida, sin compilación)
  3. Los candidatos ordenados se combinan con la configuración de CSS para crear una clave de caché
  4. En un acierto de caché: se lee de disco el CSS compilado y se inyecta
  5. En un fallo de caché: TailwindPHP::generate() compila el CSS, lo escribe en el directorio de caché y lo inyecta

El CSS compilado se inyecta así:

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

Esto incluye el preflight de Tailwind (restablecimiento CSS) y todas las clases de utilidad coincidentes.

Editor (lado del cliente)

Dentro del editor de bloques, se ejecuta en el cliente un script Tailwind CDN incluido (compilación para navegador de Tailwind CSS v4). Ofrece una vista previa instantánea en directo mientras escribe nombres de clase, sin viajes de ida y vuelta al servidor. CDN solo se carga en el editor y nunca se sirve en el frontend.

Cuando assets.reset.enabled está activo, Blockstudio también restaura las utilidades habituales de visualización y posición de Tailwind dentro del lienzo del editor. Así se evita que las reglas de los contenedores de bloques del editor WordPress sobrescriban clases del nivel de envoltura como flex, grid, absolute, fixed y sticky, de modo que los diseños basados en utilidades se parezcan más a los del frontend.

Activar Tailwind

Añada la configuración tailwind a su blockstudio.json:

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

O actívelo mediante un filtro:

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

Cuando enabled está true, se compila e inyecta automáticamente Tailwind CSS en cada página del frontend. Puede usar clases de utilidad Tailwind en cualquier lugar: en plantillas de bloques, plantillas de temas, filtros the_content o cualquier HTML que aparezca en la salida de la página.

Salida del frontend

CSS compilado se inserta en línea de forma predeterminada, para conservar la salida de las versiones anteriores. Los sitios con muchas reglas compartidas pueden optar por una hoja de estilos con hash de contenido:

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

"output": "link" genera el archivo de caché existente tailwind/{content-hash}.css como un <link rel="stylesheet">. URL cambia cuando cambian la identidad de ejecución, los candidatos, el motor o la entrada de CSS, para que los navegadores y las cachés perimetrales puedan conservar URL antiguas de forma segura. Configure el servidor web o CDN para que envíe una cabecera Cache-Control: public, immutable de larga duración para este ámbito de caché.

La raíz de caché predeterminada es pública, bajo wp-content. Si cache.path apunta a un volumen absoluto privado, Blockstudio recurre a CSS en línea, salvo que el filtro existente blockstudio/files/url proporcione un URL público para el ámbito 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
);

Ayudantes para componer plantillas

Blockstudio ofrece el mismo motor TailwindPHP incluido a las plantillas PHP. No hace falta una copia en el tema ni una implementación alternativa:

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() acepta valores de clase anidados y resuelve conflictos entre utilidades de Tailwind. bs_tw_variants() devuelve una función invocable al estilo CVA que admite base, variantes, variantes predeterminadas, variantes compuestas, class y className.

Configuración

Tailwind v4 adopta un enfoque de configuración que prioriza CSS. En lugar de un archivo de configuración JavaScript, escriba la configuración directamente como CSS mediante la directiva @theme.

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

El valor config es una cadena de CSS que se añade después de la directiva @import "tailwindcss". Aquí puede usar cualquier sintaxis válida de 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); } }"
  }
}

Para las configuraciones multilínea, el enfoque con filtros es más práctico:

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

Clases de utilidad personalizadas

Para definir alias de clase reutilizables, use @layer utilities directamente en la cadena de configuración con la directiva @apply de 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; } }"
  }
}

Esto compila estas clases junto con todas las utilidades estándar de Tailwind. Funcionan tanto en el frontend (compilación del lado del servidor) como en el editor (vista previa de CDN).

Blockstudio conserva el orden canónico de las capas en cascada de Tailwind: theme, base, components y, después, utilities. Esto coincide con Tailwind CSS, por lo que las reglas de las capas posteriores pueden sobrescribir las anteriores como se espera.

Tipo de campo Classes

Para usar clases de Tailwind en un campo classes de un bloque con autocompletado, establezca tailwind: true en el campo:

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

Cuando tailwind está true:

  • El campo ofrece sugerencias de autocompletado de toda la lista de clases de Tailwind
  • El script Tailwind CDN se carga en el editor para la vista previa en tiempo real
  • Las clases se guardan como una cadena separada por espacios en los atributos del bloque

Use el valor de clases en su plantilla:

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

Referencia de configuración

Opción Tipo Predeterminado Descripción
enabled booleano false Habilita la compilación de Tailwind CSS en el frontend
config cadena "" Cadena de configuración que prioriza Tailwind v4 CSS

Configuración mediante JSON

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

Configuración mediante filtros

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

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

Caché

Blockstudio usa una estrategia de almacenamiento en caché personalizada, diseñada para la arquitectura basada en utilidades de Tailwind.

Cómo funciona la caché

En lugar de generar un hash de todo el HTML de la página (lo que invalidaría la caché en cada solicitud por los nonces, las marcas de tiempo y otros contenidos dinámicos), Blockstudio extrae del HTML solo los candidatos de clase CSS. Ordena estos candidatos y los combina con la configuración de CSS para generar una clave de caché estable.

Esto significa que:

  • Dos páginas que usan el mismo conjunto de clases de Tailwind comparten el mismo archivo CSS en caché, aunque su HTML sea completamente distinto
  • El contenido dinámico, como los nonces, las barras de usuarios que iniciaron sesión, los recuentos de comentarios y las marcas de tiempo, no invalida la caché
  • La caché solo se invalida cuando cambia el conjunto de clases de CSS de una página o cambia la configuración de Tailwind

Cuando un entorno de ejecución usa una fuente de descubrimiento lógica, la fuente seleccionada y el contexto de ejecución también forman parte del espacio de nombres de la caché. El CSS válido más reciente queda aislado entre las vistas previas y no puede filtrarse de una selección de fuente a otra.

Ubicación de la caché

Los archivos de caché se guardan en:

Código
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

El cache.path configurado, la identidad actual de multisitio y la identidad completa del entorno de ejecución determinan el prefijo exacto. Cada archivo lleva el nombre de un hash MD5: {hash}.css.

Borrar la caché

Elimine el contenido del directorio de caché para forzar la recompilación:

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

O mediante WP-CLI:

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

La siguiente solicitud del frontend recompilará y almacenará automáticamente CSS en la caché.

Filtros

blockstudio/tailwind/css

Modifique la entrada CSS antes de la compilación. La cadena de entrada CSS empieza con @import "tailwindcss";, seguido de cualquier configuración. Use este filtro para añadir directivas CSS adicionales, reglas @layer personalizadas o importaciones de complementos.

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

La entrada completa CSS que se compila tiene este aspecto:

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

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

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

Búfer de salida

La compilación de Tailwind se integra con el sistema de búfer de salida de Blockstudio. El búfer captura el HTML completo de la página cuando WordPress termina de renderizarla, lo que permite a Tailwind analizar todas las clases de cada fuente: plantillas de bloques, plantillas de temas, salida de complementos, filtros de the_content y áreas de widgets.

El filtro de compilación se ejecuta con prioridad 999999 en el hook blockstudio/buffer/output, para procesar el HTML final después de todas las demás modificaciones. El búfer se inicia en la acción template_redirect, por lo que solo se ejecuta en las solicitudes del frontend, no en el administrador, REST API ni en contextos AJAX.

El almacenamiento en búfer de todo el documento hace posible esta función, por lo que viene habilitado de forma predeterminada. Si un sitio no usa Tailwind ni recursos de bloques, puede desactivarlo:

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

Si se devuelve false, se omite por completo el búfer, lo que también desactiva la compilación de Tailwind y la incorporación de los estilos y scripts de los bloques en la cabecera y el pie de página.

Arquitectura

Código
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

Ejemplo completo

Una configuración funcional completa con colores de tema personalizados y un bloque que los 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>

En el frontend, esto se renderiza con todas las utilidades de Tailwind y los colores personalizados del tema compilados en una única etiqueta <style> integrada en la página.

Crear una biblioteca de bloques

Tokens de diseño, utilidades personalizadas y la configuración completa de Tailwind v4 para un tema listo para producción.