Importações e módulos virtuais

TailwindPHP resolve regras @import antes da compilação. As importações podem apontar para módulos virtuais integrados (tailwindcss e outros), para arquivos no disco por meio da opção importPaths ou para qualquer conteúdo retornado por um resolvedor personalizado.

Módulos virtuais

@import "tailwindcss" é o ponto de entrada usado pela maioria dos projetos. Ele se expande para as quatro linhas abaixo — a declaração da ordem das camadas e as três subimportações, cada uma atribuída à sua camada de cascata:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

Cada subimportação também é um módulo virtual que você pode importar separadamente. Os módulos virtuais disponíveis são:

Importar as partes individualmente permite ignorar o Preflight ou reordenar as camadas (veja abaixo).

Animações com tw-animate-css

tw-animate-css é uma biblioteca de animações TailwindCSS v4 — uma substituição direta para tailwindcss-animate. Ela vem como módulo virtual integrado; portanto, importá-la junto com a camada de utilidades faz com que suas classes de animação de entrada e saída sejam compiladas como qualquer outra utilidade:

@import "tw-animate-css";
@import "tailwindcss/utilities.css";

As utilidades de animação incluem:

• Entrada / saída — animate-in, animate-out
• Aparecimento gradual — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Rotação — spin-in, spin-out
• Desfoque — blur-in, blur-out
• Deslizamento — slide-in-from-top / -bottom / -left / -right e o correspondente slide-out-to-*, além de -start / -end compatíveis com RTL
• Temporização — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate e fill-mode-none / -forwards / -backwards / -both
• Estado de reprodução — running, paused
• Animações de componentes — accordion-down / accordion-up, collapsible-down / collapsible-up e caret-blink

Essas classes podem ser combinadas com variantes Tailwind como qualquer outra utilidade, o que as torna ideais para padrões de diálogo e menus suspensos do shadcn/ui.

A opção importPaths

Para resolver @import usando o sistema de arquivos, passe importPaths no formato de array de generate(). Ele aceita um único caminho, um diretório ou um array de qualquer um deles.

use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);

Importações aninhadas

As importações dentro de um arquivo carregado são resolvidas em relação a esse arquivo. Se /path/to/styles.css contiver @import "./components/buttons.css", o caminho será resolvido em relação a /path/to/:

/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

@theme {
    --color-brand: #3b82f6;
}

Desduplicação

Importar o mesmo arquivo ou módulo virtual mais de uma vez não faz nada após a primeira importação — linhas @import "tailwindcss" repetidas ou dois arquivos que importam a mesma parte são desduplicados automaticamente. Isso também protege contra importações circulares.

Resolvedor personalizado

Para sistemas de arquivos virtuais, bancos de dados ou qualquer fonte que não seja o sistema de arquivos, passe uma função como importPaths. Ela recebe o URI da importação e o diretório base usado para resolvê-la, e retorna CSS ou null:

use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);

Quando $uri for null (a primeira chamada, também com um segundo argumento null), retorne a entrada CSS. Para qualquer outro URI, retorne seu conteúdo CSS ou null para recorrer à busca no sistema de arquivos, que ignora a importação silenciosamente quando nada é encontrado.

Preflight

Preflight é a redefinição base opinativa de Tailwind, criada sobre modern-normalize. Ela reduz inconsistências entre navegadores para que as utilidades se comportem de maneira previsível. Entre outras coisas, remove margens padrão, remove os estilos de títulos e listas, define imagens como elementos de bloco, redefine estilos de borda para que apenas border-width desenhe uma borda e permite que os botões herdem as fontes.

O Preflight vem incluído em @import "tailwindcss" — se você importar o pacote completo, ele já estará disponível:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);

Estendendo o Preflight

Adicione seus próprios estilos base sobre o Preflight com @layer base:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);

Desativando o Preflight

Ao integrar a ferramenta a um projeto existente, importe apenas as partes necessárias e omita a linha do Preflight:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);

Modificadores de importação

Ao importar arquivos de Tailwind individualmente, coloque os modificadores nas importações que eles afetam:

/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);

Importações de referência

@import "…" reference carrega um arquivo apenas para obter suas definições: valores de @theme, definições de @utility e de @custom-variant dentro dele podem ser usadas, mas o arquivo não emite nenhum CSS próprio. É equivalente a envolver o conteúdo do arquivo em @media reference { … }, o que você também pode escrever diretamente:

@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}

bg-brand então é compilado como background-color: var(--color-brand, #f00); e nenhuma declaração --color-brand é emitida.

Duas limitações da versão atual (#14):

• Coloque importações de referência e blocos @media reference após o @import de tailwindcss ou tailwindcss/utilities.css. Se forem colocados antes, toda a saída ficará vazia.
• reference nos módulos virtuais integrados (@import "tailwindcss" reference;) ainda não tem efeito: o tema, o Preflight e as utilidades continuam sendo emitidos.

Continue com Tema para ver as variáveis do tema ou com @source para controlar quais arquivos são analisados em busca de nomes de classes.