Imports und virtuelle Module

TailwindPHP löst @import-Regeln vor der Kompilierung auf. Imports können auf integrierte virtuelle Module (tailwindcss und weitere), auf Dateien über die Option importPaths oder auf beliebige Inhalte verweisen, die du von einem benutzerdefinierten Resolver zurückgibst.

Virtuelle Module

@import "tailwindcss" ist der Einstiegspunkt, den die meisten Projekte verwenden. Es wird zu den vier folgenden Zeilen erweitert – der Deklaration der Schichtenreihenfolge und den drei Unter-Imports, die jeweils ihrer Kaskadenschicht zugewiesen sind:

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

Jeder Unter-Import ist selbst ein virtuelles Modul, das du einzeln importieren kannst. Verfügbare virtuelle Module:

Wenn du die Teile einzeln importierst, kannst du Preflight überspringen oder die Schichten neu anordnen (siehe unten).

Animationen mit tw-animate-css

tw-animate-css ist eine Animationsbibliothek für TailwindCSS v4 – ein direkter Ersatz für tailwindcss-animate. Sie wird als integriertes virtuelles Modul bereitgestellt. Importierst du sie zusammen mit der Utilities-Schicht, werden ihre Ein- und Austrittsanimationsklassen wie jedes andere Utility kompiliert:

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

Die Animations-Utilities umfassen:

• Ein- und Austritt — animate-in, animate-out
• Einblenden — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Drehen — spin-in, spin-out
• Unschärfe — blur-in, blur-out
• Gleiten — slide-in-from-top / -bottom / -left / -right und die entsprechenden slide-out-to-* sowie RTL-fähige -start / -end
• Zeitsteuerung — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate und fill-mode-none / -forwards / -backwards / -both
• Wiedergabestatus — running, paused
• Komponentenanimationen — accordion-down / accordion-up, collapsible-down / collapsible-up und caret-blink

Diese Klassen lassen sich wie jedes andere Utility mit Tailwind-Varianten kombinieren und eignen sich dadurch direkt für Dialog- und Dropdown-Muster aus shadcn/ui.

Die Option importPaths

Damit @import im Dateisystem aufgelöst wird, übergib importPaths in der Array-Form von generate(). Akzeptiert werden ein einzelner Pfad, ein Verzeichnis oder ein Array daraus.

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

Verschachtelte Imports

Imports in einer geladenen Datei werden relativ zu dieser Datei aufgelöst. Wenn /path/to/styles.css @import "./components/buttons.css" enthält, wird der Pfad relativ zu /path/to/ aufgelöst:

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

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

Deduplizierung

Wird dieselbe Datei oder dasselbe virtuelle Modul mehrmals importiert, bleiben alle weiteren Imports nach dem ersten wirkungslos. Wiederholte @import "tailwindcss"-Zeilen oder zwei Dateien, die beide dasselbe Teilmodul importieren, werden automatisch dedupliziert. So werden auch zirkuläre Imports verhindert.

Benutzerdefinierter Resolver

Für virtuelle Dateisysteme, Datenbanken oder andere Quellen, die kein Dateisystem sind, übergib eine aufrufbare Funktion als importPaths. Sie erhält die Import-URI und das Basisverzeichnis, relativ zu dem der Import aufgelöst wird, und gibt CSS oder null zurück:

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

Wenn $uri null ist (beim ersten Aufruf, auch mit null als zweitem Argument), gib die CSS-Datei zurück. Bei jeder anderen URI gib ihren Inhalt als CSS zurück oder null, damit die Suche im Dateisystem übernimmt. Wird nichts gefunden, wird der Import stillschweigend übersprungen.

Preflight

Preflight ist Tailwinds meinungsstarker Basisreset und baut auf modern-normalize auf. Er gleicht Unterschiede zwischen Browsern aus, damit Utilities sich zuverlässig verhalten. Unter anderem entfernt er Standardabstände, hebt die Standardstile von Überschriften und Listen auf, setzt Bilder auf Blockebene, setzt Rahmenstile zurück, sodass nur border-width einen Rahmen zeichnet, und lässt Buttons die Schriftarten erben.

Preflight ist in @import "tailwindcss" enthalten. Wenn du das vollständige Paket importierst, ist es bereits dabei:

use TailwindPHP\tw;

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

Preflight erweitern

Füge mit @layer base eigene Basisstile zu Preflight hinzu:

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 deaktivieren

Wenn du Preflight in ein bestehendes Projekt integrierst, importiere nur die benötigten Teile und lass die Preflight-Zeile 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);
    ',
]);

Import-Modifikatoren

Wenn du Tailwinds Dateien einzeln importierst, gehören Modifikatoren zu den Imports, auf die sie sich auswirken:

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

Referenz-Imports

@import "…" reference lädt eine Datei ausschließlich für ihre Definitionen: @theme-Werte sowie Definitionen für @utility und @custom-variant darin können verwendet werden, aber die Datei gibt selbst keine CSS aus. Das entspricht dem Umschließen des Dateiinhalts mit @media reference { … }, was du auch direkt schreiben kannst:

@import "tailwindcss/utilities.css";

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

bg-brand wird dann zu background-color: var(--color-brand, #f00); kompiliert und es wird keine --color-brand-Deklaration ausgegeben.

Zwei Einschränkungen der aktuellen Version (#14):

• Platziere Referenz-Imports und @media reference-Blöcke nach dem @import von tailwindcss oder tailwindcss/utilities.css. Stehen sie davor, ist die gesamte Ausgabe leer.
• reference auf den integrierten virtuellen Modulen (@import "tailwindcss" reference;) hat noch keine Wirkung: Theme, Preflight und Utilities werden weiterhin ausgegeben.

Mach mit Theme für Theme-Variablen oder mit @source weiter, um festzulegen, welche Dateien nach Klassennamen durchsucht werden.