Imports et modules virtuels

TailwindPHP résout les règles @import avant la compilation. Les imports peuvent cibler des modules virtuels intégrés (tailwindcss et autres), des fichiers sur disque via l’option importPaths, ou tout contenu renvoyé par un résolveur personnalisé.

Modules virtuels

@import "tailwindcss" est le point d’entrée utilisé par la plupart des projets. Il se développe en quatre lignes : la déclaration de l’ordre des couches, puis les trois sous-imports, chacun affecté à sa couche de cascade :

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

Chaque sous-import est lui-même un module virtuel que vous pouvez importer séparément. Voici les modules virtuels disponibles :

Importer les différentes parties séparément permet d’ignorer Preflight ou de réorganiser les couches (voir ci-dessous).

Animations avec tw-animate-css

tw-animate-css est une bibliothèque d’animations TailwindCSS v4, conçue comme un remplacement direct de tailwindcss-animate. Elle est fournie sous forme de module virtuel intégré ; son import avec la couche des utilitaires permet donc de compiler ses classes d’animation d’entrée et de sortie comme n’importe quel autre utilitaire :

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

Les utilitaires d’animation couvrent les éléments suivants :

• Entrée / sortie — animate-in, animate-out
• Fondu — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Rotation — spin-in, spin-out
• Flou — blur-in, blur-out
• Glissement — slide-in-from-top / -bottom / -left / -right et les variantes slide-out-to-* correspondantes, ainsi que -start / -end compatibles avec RTL
• Temporalité — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate et fill-mode-none / -forwards / -backwards / -both
• État de lecture — running, paused
• Animations de composants — accordion-down / accordion-up, collapsible-down / collapsible-up et caret-blink

Ces classes s’empilent avec les variantes Tailwind comme tout autre utilitaire, ce qui les rend parfaitement adaptées aux modèles de boîtes de dialogue et de menus déroulants shadcn/ui.

L’option importPaths

Pour résoudre @import à partir du système de fichiers, passez importPaths dans la forme tableau de generate(). Elle accepte un chemin unique, un répertoire ou un tableau de l’un ou l’autre.

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

Imports imbriqués

Les imports contenus dans un fichier chargé sont résolus par rapport à ce fichier. Si /path/to/styles.css contient @import "./components/buttons.css", le chemin est résolu par rapport à /path/to/ :

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

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

Déduplication

L’importation répétée d’un même fichier ou module virtuel est sans effet après la première fois : les lignes @import "tailwindcss" répétées, ou deux fichiers important la même partie, sont dédupliqués automatiquement. Cela protège également contre les imports circulaires.

Résolveur personnalisé

Pour les systèmes de fichiers virtuels, les bases de données ou toute source autre que le système de fichiers, passez une fonction appelable en tant que importPaths. Elle reçoit l’URI d’import et le répertoire de base utilisé pour le résoudre, puis renvoie 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
    },
]);

Lorsque $uri vaut null (au premier appel, avec également un deuxième argument null), renvoyez le CSS d’entrée. Pour toute autre URI, renvoyez son contenu CSS ou null pour revenir à la recherche dans le système de fichiers, qui ignore silencieusement l’import si aucun résultat n’est trouvé.

Preflight

Preflight est la réinitialisation de base opinionnée de Tailwind, construite sur modern-normalize. Elle lisse les incohérences entre navigateurs pour que les utilitaires se comportent de manière prévisible. Elle supprime notamment les marges par défaut, retire la mise en forme des titres et des listes, affiche les images comme des blocs, réinitialise les styles de bordure pour que seul border-width dessine une bordure et fait hériter aux boutons les polices.

Preflight est inclus dans @import "tailwindcss" : si vous importez le bundle complet, il est déjà disponible :

use TailwindPHP\tw;

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

Étendre Preflight

Ajoutez vos propres styles de base par-dessus Preflight avec @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; }
        }
    ',
]);

Désactiver Preflight

Pour intégrer l’outil à un projet existant, importez uniquement les parties nécessaires et omettez la ligne 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);
    ',
]);

Modificateurs d’import

Lorsque vous importez individuellement les fichiers de Tailwind, les modificateurs s’ajoutent aux imports concernés :

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

Imports de référence

@import "…" reference charge un fichier uniquement pour ses définitions : les valeurs @theme ainsi que les définitions @utility et @custom-variant qu’il contient sont utilisables, mais le fichier ne génère aucune déclaration CSS. Cela revient à envelopper le contenu du fichier dans @media reference { … }, ce que vous pouvez aussi écrire directement :

@import "tailwindcss/utilities.css";

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

bg-brand est alors compilé en background-color: var(--color-brand, #f00); et aucune déclaration --color-brand n’est émise.

Deux limites de la version actuelle (#14) :

• Placez les imports de référence et les blocs @media reference après le @import de tailwindcss ou de tailwindcss/utilities.css. Placés avant, ils produisent une sortie vide.
• reference n’a pas encore d’effet sur les modules virtuels intégrés (@import "tailwindcss" reference;) : le thème, Preflight et les utilitaires sont toujours émis.

Poursuivez avec Thème pour les variables de thème, ou @source pour définir les fichiers analysés à la recherche de noms de classes.