Imports en virtuele modules

TailwindPHP verwerkt @import-regels vóór de compilatie. Imports kunnen verwijzen naar ingebouwde virtuele modules (tailwindcss en vergelijkbare modules), naar bestanden op schijf via de optie importPaths, of naar alles wat je via een aangepaste resolver retourneert.

Virtuele modules

@import "tailwindcss" is het startpunt voor de meeste projecten. Het wordt uitgebreid tot de vier onderstaande regels: de declaratie van de laagvolgorde plus de drie subimports, elk toegewezen aan de eigen cascadelaag:

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

Elke subimport is zelf een virtuele module die je afzonderlijk kunt importeren. De beschikbare virtuele modules zijn:

Door de onderdelen afzonderlijk te importeren kun je Preflight overslaan of de lagen anders rangschikken (zie hieronder).

Animaties met tw-animate-css

tw-animate-css is een animatiebibliotheek voor TailwindCSS v4 — een directe vervanging voor tailwindcss-animate. De bibliotheek is beschikbaar als ingebouwde virtuele module. Importeer die naast de laag met hulpprogramma's om de klassen voor in- en uitgaande animaties te compileren zoals elk ander hulpprogramma:

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

De animatiehulpprogramma's omvatten:

• In- en uitgaan — animate-in, animate-out
• Vervagen — fade-in, fade-out
• Zoomen — zoom-in, zoom-out
• Draaien — spin-in, spin-out
• Vervagen — blur-in, blur-out
• Schuiven — slide-in-from-top / -bottom / -left / -right en de bijbehorende slide-out-to-*, plus RTL-bewuste -start / -end
• Timing — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate, en fill-mode-none / -forwards / -backwards / -both
• Afspeelstatus — running, paused
• Componentanimaties — accordion-down / accordion-up, collapsible-down / collapsible-up en caret-blink

Deze klassen kunnen net als elk ander hulpprogramma worden gestapeld met Tailwind-varianten. Daardoor passen ze direct in shadcn/ui-patronen voor dialogen en dropdowns.

De optie importPaths

Geef importPaths mee in de arrayvorm van generate() om @import op basis van het bestandssysteem te verwerken. Je kunt één pad, een map of een array van beide opgeven.

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

Geneste imports

Imports in een geladen bestand worden relatief aan dat bestand verwerkt. Als /path/to/styles.css @import "./components/buttons.css" bevat, wordt het pad opgelost ten opzichte van /path/to/:

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

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

Duplicaten verwijderen

Als hetzelfde bestand of dezelfde virtuele module meerdere keren wordt geïmporteerd, gebeurt er na de eerste keer niets meer — herhaalde regels met @import "tailwindcss", of twee bestanden die hetzelfde gedeeltelijke bestand importeren, worden automatisch ontdubbeld. Dit voorkomt ook circulaire imports.

Aangepaste resolver

Geef voor virtuele bestandssystemen, databases of andere bronnen die geen bestandssysteem gebruiken een aanroepbare functie mee als importPaths. Deze ontvangt de import-URI en de basismap ten opzichte waarvan de import wordt verwerkt, en retourneert CSS of 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
    },
]);

Wanneer $uri null is (de eerste aanroep, ook met een tweede argument van null), retourneer je het CSS-bestand. Retourneer voor elke andere URI de inhoud van CSS, of null om terug te vallen op zoeken in het bestandssysteem. Wordt niets gevonden, dan wordt de import stilzwijgend overgeslagen.

Preflight

Preflight is de uitgesproken basisreset van Tailwind, gebouwd op modern-normalize. Deze werkt verschillen tussen browsers weg, zodat hulpprogramma's zich voorspelbaar gedragen. Zo verwijdert Preflight standaardmarges, haalt het de standaardopmaak van koppen en lijsten weg, maakt het afbeeldingen block-level, reset het randstijlen zodat alleen border-width een rand tekent, en laat het knoppen de lettertypen overnemen.

Preflight is opgenomen in @import "tailwindcss" — als je de volledige bundel importeert, is Preflight dus al inbegrepen:

use TailwindPHP\tw;

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

Preflight uitbreiden

Voeg met @layer base je eigen basisstijlen toe boven op Preflight:

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

Preflight uitschakelen

Als je dit integreert in een bestaand project, importeer dan alleen de onderdelen die je nodig hebt en laat de regel voor Preflight weg:

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

Importmodifiers

Wanneer je de bestanden van Tailwind afzonderlijk importeert, plaats je modifiers bij de imports waarop ze van toepassing zijn:

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

Referentie-imports

@import "…" reference laadt een bestand alleen om de definities eruit beschikbaar te maken: waarden van @theme en definities van @utility en @custom-variant in dat bestand kunnen worden gebruikt, maar het bestand genereert zelf geen CSS. Dit is hetzelfde als de inhoud van het bestand tussen @media reference { … } te plaatsen, wat je ook rechtstreeks kunt doen:

@import "tailwindcss/utilities.css";

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

bg-brand wordt vervolgens gecompileerd tot background-color: var(--color-brand, #f00);; er wordt geen declaratie van --color-brand gegenereerd.

Twee beperkingen in de huidige versie (#14):

• Plaats referentie-imports en blokken van @media reference na de @import van tailwindcss of tailwindcss/utilities.css. Als ze ervoor staan, wordt de volledige uitvoer leeg.
• reference heeft nog geen effect op de ingebouwde virtuele modules (@import "tailwindcss" reference;): het thema, Preflight en de hulpprogramma's worden nog steeds gegenereerd.

Lees verder bij Thema voor themavariabelen, of bij @source om te bepalen welke bestanden worden gescand op klassennamen.