Tailwind CSS
Blockstudio inclui suporte integrado a Tailwind CSS v4. Quando ativado, cada página do frontend é compilada no servidor por meio de TailwindPHP, com cache automático baseado em arquivos. No editor de blocos, um script Tailwind CDN incluído fornece pré-visualização ao vivo enquanto você edita.
Sem etapa de compilação, sem CLI, sem Node.js.
Como funciona
Blockstudio usa duas estratégias distintas de compilação, conforme o contexto:
Frontend (lado do servidor)
A cada solicitação do frontend, Blockstudio captura o HTML completo da página por meio de um buffer de saída, extrai todos os candidatos a classes CSS, compila apenas CSS que realmente está sendo usado e injeta o resultado como uma tag <style> inline antes de </head>.
Fluxo de compilação:
- WordPress renderiza o HTML completo da página em um buffer de saída
TailwindPHP::extractCandidates()analisa o HTML e extrai todos os nomes de classes potenciais de CSS (expressão regular rápida, sem compilação)- Os candidatos ordenados são combinados com a configuração de CSS para criar uma chave de cache
- Em caso de acerto no cache: o CSS compilado é lido do disco e injetado
- Em caso de erro no cache:
TailwindPHP::generate()compila CSS, grava no diretório de cache e injeta o resultado
O CSS compilado é injetado assim:
<style id="blockstudio-tailwind">
/* compiled CSS */
</style>
Isso inclui o preflight de Tailwind (reset de CSS) e todas as classes utilitárias correspondentes.
Editor (lado do cliente)
Dentro do editor de blocos, um script Tailwind CDN agrupado (compilação para navegador de Tailwind CSS v4) é executado no lado do cliente. Isso fornece pré-visualização ao vivo instantânea enquanto você digita nomes de classes, sem idas e voltas ao servidor. O CDN só é carregado no editor e nunca é servido no frontend.
Quando assets.reset.enabled está ativo, Blockstudio também restaura os utilitários comuns de exibição e posicionamento de Tailwind dentro da tela do editor. Isso impede que regras de wrapper de bloco do editor WordPress sobrescrevam classes no nível do wrapper, como flex, grid, absolute, fixed e sticky, para que layouts baseados em utilitários se pareçam mais com o frontend.
Ativar Tailwind
Adicione a configuração tailwind ao seu blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
Ou ative por meio de um filtro:
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
Quando enabled está true, Tailwind CSS é compilado e injetado automaticamente em cada página do frontend. Você pode usar classes utilitárias Tailwind em qualquer lugar: em modelos de blocos, modelos de tema, filtros the_content ou qualquer HTML que apareça na saída da página.
Saída do frontend
Por padrão, o CSS compilado é inline, preservando a saída usada pelas versões anteriores. Sites com muitas regras compartilhadas podem optar por uma folha de estilos identificada por hash de conteúdo:
{
"tailwind": {
"enabled": true,
"output": "link"
}
}
"output": "link" emite o arquivo de cache tailwind/{content-hash}.css existente como <link rel="stylesheet">. O URL muda quando a identidade de execução, os candidatos, o mecanismo ou a entrada de CSS mudam, para que navegadores e caches de borda possam manter com segurança URLs antigos. Configure o servidor Web ou CDN para enviar um cabeçalho Cache-Control: public, immutable de longa duração para este escopo de cache.
A raiz padrão do cache é pública, sob wp-content. Se cache.path apontar para um volume absoluto privado, Blockstudio usará CSS inline, a menos que o filtro blockstudio/files/url existente forneça um URL público para o escopo 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
);
Helpers para composição de modelos
Blockstudio disponibiliza o mesmo mecanismo TailwindPHP agrupado para modelos PHP. Não é necessária uma cópia no tema nem uma implementação alternativa:
$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() aceita valores de classe aninhados e resolve conflitos entre utilitários Tailwind. bs_tw_variants() retorna uma função chamável no estilo CVA que oferece suporte a base, variantes, variantes padrão, variantes compostas, class e className.
Configuração
Tailwind v4 usa uma abordagem de configuração que prioriza CSS. Em vez de um arquivo de configuração JavaScript, você escreve a configuração diretamente como CSS usando a diretiva @theme.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
O valor config é uma string CSS que é adicionada após a diretiva @import "tailwindcss". Você pode usar qualquer sintaxe válida de Tailwind v4 CSS aqui:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
Para configurações em várias linhas, a abordagem com filtro é mais prática:
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 utilitárias personalizadas
Para definir aliases de classe reutilizáveis, use @layer utilities diretamente na string de configuração com a diretiva @apply de Tailwind:
{
"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; } }"
}
}
Isso compila essas classes junto com todos os utilitários padrão de Tailwind. Elas funcionam tanto no frontend (compilação no servidor) quanto no editor (prévia de CDN).
Blockstudio preserva a ordem canônica das camadas em cascata de Tailwind:
theme, base, components e, por fim, utilities. Isso corresponde a Tailwind CSS, portanto
as regras em camadas posteriores podem sobrescrever as anteriores como esperado.
Tipo do campo de classes
Para usar classes Tailwind no campo classes de um bloco com suporte a preenchimento automático, defina tailwind: true no campo:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{
"id": "classes",
"type": "classes",
"label": "Classes",
"tailwind": true,
"default": "bg-white text-gray-900"
}
]
}
}
Quando tailwind está true:
- O campo oferece sugestões de preenchimento automático a partir da lista completa de classes Tailwind
- O script Tailwind CDN é carregado no editor para prévia ao vivo
- As classes são armazenadas como uma string separada por espaços nos atributos do bloco
Use o valor das classes no seu template:
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
Referência de configurações
| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
enabled |
booleano | false |
Ativa a compilação de Tailwind CSS no frontend |
config |
string | "" |
String de configuração que prioriza Tailwind v4 CSS |
Configuração via JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
Configuração via filtros
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
add_filter('blockstudio/settings/tailwind/config', function () {
return '@theme { --color-brand: pink; }';
});
Cache
Blockstudio usa uma estratégia de cache personalizada, projetada para a arquitetura baseada em utilitários de Tailwind.
Como o cache funciona
Em vez de calcular o hash de toda a página HTML (o que invalidaria o cache a cada solicitação devido a nonces, registros de data e hora e outros conteúdos dinâmicos), Blockstudio extrai apenas os candidatos de classe CSS de HTML. Esses candidatos são ordenados e têm seus hashes calculados junto com a configuração CSS para gerar uma chave de cache estável.
Isso significa que:
- Duas páginas que usam o mesmo conjunto de classes Tailwind compartilham o mesmo arquivo CSS em cache, mesmo que seu HTML seja completamente diferente
- Conteúdos dinâmicos, como nonces, barras de usuários conectados, contagens de comentários e registros de data e hora, não invalidam o cache
- O cache só é invalidado quando o conjunto de classes CSS de uma página muda ou quando a configuração Tailwind é alterada
Quando um runtime usa uma fonte de descoberta lógica, a fonte selecionada e o contexto do runtime também participam do namespace do cache. O CSS válido mais recente fica isolado entre as prévias e não pode vazar de uma seleção de fonte para outra.
Local do cache
Os arquivos de cache são armazenados em:
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
O cache.path configurado, a identidade multisite atual e a identidade completa do runtime determinam o prefixo exato. Cada arquivo recebe um nome com um hash MD5:
{hash}.css.
Limpar o cache
Exclua o conteúdo do diretório de cache para forçar a recompilação:
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
Ou via WP-CLI:
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
A próxima solicitação ao frontend recompilará e armazenará CSS em cache automaticamente.
Filtros
blockstudio/tailwind/css
Modifique a entrada CSS antes da compilação. A string de entrada CSS começa com @import "tailwindcss";, seguida de qualquer configuração. Use este filtro para adicionar diretivas CSS, regras @layer personalizadas ou importações 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;
});
A entrada completa de CSS compilada tem esta aparência:
/* Base import */
@import 'tailwindcss';
/* Config from settings (if set) */
@theme {
--color-brand: pink;
}
/* Anything added via the blockstudio/tailwind/css filter */
Buffer de saída
A compilação de Tailwind se integra ao sistema de buffer de saída de Blockstudio. O buffer captura o HTML completo da página após WordPress terminar de renderizar, permitindo que Tailwind examine todas as classes de cada fonte: templates de blocos, templates de temas, saída de plugins, filtros de the_content e áreas de widgets.
O filtro de compilação é executado na prioridade 999999 no hook blockstudio/buffer/output, garantindo que processe o HTML final após todas as outras modificações. O buffer é iniciado na ação template_redirect, o que significa que só é executado em solicitações ao frontend, e não no painel administrativo, em REST API ou em contextos AJAX.
O buffering do documento inteiro torna isso possível, por isso vem ativado por padrão. Um site que não usa Tailwind nem recursos de blocos pode desativá-lo:
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
Retornar false ignora completamente o buffer, o que também desativa a compilação de Tailwind e a transferência dos estilos e scripts de blocos para o cabeçalho e o rodapé.
Arquitetura
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
Exemplo completo
Uma configuração funcional completa, com cores de tema personalizadas e um bloco que as utiliza:
{
"$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>
Isso é renderizado no frontend com todos os utilitários de Tailwind e as cores personalizadas do tema compilados em uma única tag <style> embutida.
Criando uma biblioteca de blocos
Tokens de design, utilitários personalizados e a configuração completa de Tailwind v4 para um tema pronto para produção.