Importaciones y módulos virtuales

TailwindPHP resuelve las reglas @import antes de la compilación. Las importaciones pueden apuntar a módulos virtuales integrados (tailwindcss y otros), a archivos en disco mediante la opción importPaths o a cualquier contenido que devuelva un resolutor personalizado.

Módulos virtuales

@import "tailwindcss" es el punto de entrada que usa la mayoría de los proyectos. Se expande en las cuatro líneas siguientes: la declaración del orden de capas y las tres subimportaciones, cada una asignada a su capa de cascada:

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

Cada subimportación es, a su vez, un módulo virtual que puedes importar por separado. Los módulos virtuales disponibles son:

Importar las partes por separado te permite omitir Preflight o reordenar las capas (consulta más abajo).

Animaciones con tw-animate-css

tw-animate-css es una biblioteca de animaciones TailwindCSS v4, un reemplazo directo de tailwindcss-animate. Se incluye como módulo virtual integrado, así que al importarla junto con la capa de utilidades, sus clases de animación de entrada y salida se compilan como cualquier otra utilidad:

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

Las utilidades de animación incluyen:

• Entrada / salida — animate-in, animate-out
• Desvanecimiento — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Giro — spin-in, spin-out
• Desenfoque — blur-in, blur-out
• Deslizamiento — slide-in-from-top / -bottom / -left / -right y los correspondientes slide-out-to-*, además de -start / -end compatibles con RTL
• Temporización — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate y fill-mode-none / -forwards / -backwards / -both
• Estado de reproducción — running, paused
• Animaciones de componentes — accordion-down / accordion-up, collapsible-down / collapsible-up y caret-blink

Estas clases se combinan con variantes Tailwind como cualquier otra utilidad, por lo que encajan directamente en patrones de diálogo y menú desplegable de shadcn/ui.

La opción importPaths

Para resolver @import en el sistema de archivos, pasa importPaths en el formato de matriz de generate(). Acepta una ruta, un directorio o una matriz de cualquiera de ellos.

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',
]);

Importaciones anidadas

Las importaciones dentro de un archivo cargado se resuelven en relación con ese archivo. Si /path/to/styles.css contiene @import "./components/buttons.css", la ruta se resuelve con respecto a /path/to/:

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

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

Deduplicación

Importar el mismo archivo o módulo virtual más de una vez no tiene efecto después de la primera vez: las líneas @import "tailwindcss" repetidas, o dos archivos que importan el mismo parcial, se deduplican automáticamente. Esto también evita las importaciones circulares.

Resolutor personalizado

Para sistemas de archivos virtuales, bases de datos o cualquier origen que no sea el sistema de archivos, pasa una función como importPaths. Recibe la URI de importación y el directorio base desde el que se resuelve la importación, y devuelve CSS o 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
    },
]);

Cuando $uri es null (la primera llamada, también con un segundo argumento null), devuelve la entrada CSS. Para cualquier otra URI, devuelve su contenido CSS o null para recurrir a la búsqueda en el sistema de archivos, que omite la importación en silencio si no encuentra nada.

Preflight

Preflight es el restablecimiento base con criterios definidos de Tailwind, basado en modern-normalize. Suaviza las inconsistencias entre navegadores para que las utilidades se comporten de forma predecible. Entre otras cosas, elimina los márgenes predeterminados, quita el estilo de los encabezados y las listas, convierte las imágenes en elementos de bloque, restablece los estilos de borde para que solo border-width dibuje un borde y permite que los botones hereden las fuentes.

Preflight viene incluido en @import "tailwindcss"; si importas el paquete completo, ya lo tienes:

use TailwindPHP\tw;

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

Ampliar Preflight

Añade tus propios estilos base sobre Preflight con @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; }
        }
    ',
]);

Desactivar Preflight

Al integrarlo en un proyecto existente, importa solo las partes que necesites y omite la línea de 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 importación

Al importar los archivos de Tailwind por separado, los modificadores se añaden a las importaciones que afectan:

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

Importaciones de referencia

@import "…" reference carga un archivo solo para usar sus definiciones: los valores de @theme y las definiciones de @utility y @custom-variant que contiene están disponibles, pero el archivo no genera ningún CSS propio. Equivale a envolver el contenido del archivo en @media reference { … }, algo que también puedes escribir directamente:

@import "tailwindcss/utilities.css";

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

bg-brand se compila entonces como background-color: var(--color-brand, #f00); y no se emite ninguna declaración de --color-brand.

Dos limitaciones de la versión actual (#14):

• Coloca las importaciones de referencia y los bloques @media reference después de @import de tailwindcss o tailwindcss/utilities.css. Si los colocas antes, toda la salida queda vacía.
• reference en los módulos virtuales integrados (@import "tailwindcss" reference;) aún no tiene efecto: el tema, Preflight y las utilidades se siguen emitiendo.

Continúa con Theme para consultar las variables del tema, o con @source para controlar qué archivos se analizan en busca de nombres de clase.