Tailwind CSS mit Symfony AssetMapper einrichten: Das moderne Setup ohne Node.js

1. Warum AssetMapper statt Webpack Encore?

Symfony Webpack Encore war lange die Standardlösung für das Asset-Management in Symfony-Projekten: JavaScript-Bundles, CSS-Preprocessing, Babel-Transpilation. Für viele Projekte brachte das erheblichen Overhead: Eine node_modules-Instanz mit tausenden Paketen, komplexe Webpack-Konfiguration und eine lange Build-Zeit, die jeden Deployment-Prozess verlangsamt. Mit Symfony 6.3 und dem Tailwind CSS Symfony AssetMapper gibt es eine Alternative, die für viele Projekte deutlich besser passt: Der AssetMapper behandelt JavaScript-Dateien als ES-Module, die der Browser nativ laden kann, und die importmap mappt Paket-Pfade auf CDN-URLs oder lokale Dateien.

Der AssetMapper basiert auf einer einfachen Idee: Moderne Browser unterstützen ES-Module nativ. Es ist nicht mehr nötig, JavaScript zu bündeln, damit es im Browser läuft. Der AssetMapper kopiert Asset-Dateien mit Content-Hash-Fingerprint in ein öffentliches Verzeichnis und verwaltet die importmap automatisch. Für CSS ist der AssetMapper kein vollständiger Ersatz für PostCSS – hier kommt die Tailwind CSS Symfony-Kombination mit der Standalone CLI ins Spiel: Tailwind CSS verarbeitet CSS ohne npm, nur mit einem einzigen Binary, das keine Node.js-Installation erfordert.

2. Symfony AssetMapper: Grundlagen und Konzepte

Der Symfony AssetMapper wird als Bundle über composer require symfony/asset-mapper installiert. Nach der Installation gibt es zwei neue Konfigurationsdateien: config/packages/asset_mapper.yaml definiert die Verzeichnisse, die der AssetMapper überwacht, und importmap.php enthält die importmap-Konfiguration – welche JavaScript-Pakete verfügbar sind und wo sie herkommen. Der Befehl php bin/console importmap:require stimulus lädt Stimulus als Paket herunter und trägt es automatisch in importmap.php ein.

Das Verzeichnis assets/ im Projekt-Root ist der Standard-Eingangspunkt für Quelldateien. Der AssetMapper überwacht dieses Verzeichnis und erzeugt beim Build oder beim ersten Request versionierte Kopien in public/assets/. Die Dateinamen enthalten einen Content-Hash – app.1a2b3c.css – der sich ändert, wenn der Dateiinhalt ändert. Das macht Cache-Busting automatisch, ohne manuelles Versionierungsmanagement. Für das Tailwind CSS Symfony AssetMapper-Setup ist das Zusammenspiel wichtig: Tailwind CSS schreibt seine Ausgabedatei in das assets/-Verzeichnis, der AssetMapper versioniert sie und bindet sie in Twig-Templates ein.

3. Tailwind CSS Standalone CLI: Setup und Konfiguration

Die Tailwind CSS Standalone CLI ist eine vorkompilierte Binary, die Tailwind CSS ohne Node.js und ohne npm verarbeitet. Sie ist für Linux (x64, arm64), macOS (x64, arm64) und Windows verfügbar und enthält alle notwendigen Abhängigkeiten als Single-File-Binary. Für das Tailwind CSS Symfony-Setup ist das der entscheidende Vorteil: Der Build-Server muss kein Node.js installiert haben. Die Binary wird einmalig heruntergeladen, im Projekt eingecheckt oder in einem separaten Download-Schritt bereitgestellt, und danach für alle CSS-Builds verwendet.

Die Installation im Symfony-Projekt: Die Binary wird in das Projektverzeichnis (typischerweise bin/tailwind) heruntergeladen und ausführbar gemacht. Das Eingabe-CSS liegt in assets/styles/app.css und enthält die Tailwind-Direktiven. Die Ausgabe wird in dasselbe Verzeichnis oder ein Unterverzeichnis geschrieben, sodass der AssetMapper sie aufnehmen kann. Ein wichtiger Aspekt beim Tailwind CSS Symfony AssetMapper-Setup: Die Ausgabedatei muss im assets/-Verzeichnis liegen, damit der AssetMapper sie versioniert. Alternativ kann ein separates Output-Verzeichnis konfiguriert werden, aber das erfordert zusätzliche AssetMapper-Pfad-Konfiguration.

/* assets/styles/app.css — Main CSS entry point for Tailwind CSS + Symfony */

/* Tailwind base reset and preflight */
@tailwind base;

/* Tailwind component classes (if used) */
@tailwind components;

/* All utility classes — generated from Twig, PHP and JS content scan */
@tailwind utilities;

/* Custom base styles after Tailwind */
@layer base {
  :root {
    --color-brand: #0ea5e9;
    --color-brand-dark: #0284c7;
  }

  html {
    @apply scroll-smooth;
  }

  body {
    @apply font-sans text-slate-800 antialiased;
  }
}

/* Custom component classes that are too complex for utilities alone */
@layer components {
  .btn-primary {
    @apply bg-sky-600 text-white font-semibold px-5 py-2.5 rounded-xl
           hover:bg-sky-700 focus:outline-none focus:ring-2 focus:ring-sky-500 focus:ring-offset-2
           transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed;
  }

  .card {
    @apply bg-white border border-slate-200 rounded-2xl p-6 shadow-sm;
  }
}

4. tailwind.config.js für Symfony-Projekte

Die tailwind.config.js für ein Symfony-Projekt muss alle Stellen abdecken, an denen Tailwind-Klassen vorkommen können: Twig-Templates, PHP-Controller (wenn Klassen als PHP-Strings generiert werden), JavaScript-Dateien im assets/-Verzeichnis und MDX- oder andere Dokumentationsdateien. Die content-Konfiguration muss alle diese Pfade einschließen, damit der Purge-Mechanismus keine benötigten Klassen entfernt.

Besonders wichtig im Tailwind CSS Symfony-Kontext: Twig-Templates, die Tailwind-Klassen aus PHP-Variablen oder Twig-Variablen zusammensetzen, sind ein häufiger Fallstrick. Wenn ein Twig-Template class="bg-{ { category.color } }-500" rendert, ist bg-{ { category.color } }-500 kein vollständiger Klassenstring für Tailwind's Scanner. Hier gilt dieselbe Regel wie in jedem anderen Tailwind-Projekt: Vollständige Klassenstrings in einer Lookup-Datei oder in der Safelist. Die Symfony-Konfigurationsstruktur bietet eine natürliche Lösung: Eine PHP-Datei config/tailwind-classes.php, die ein Array mit allen vollständigen Klassen enthält und im content-Path von Tailwind eingetragen ist.

// tailwind.config.js — Symfony + AssetMapper project configuration
/** @type {import('tailwindcss').Config} */
module.exports = {
  // Scan all locations where Tailwind classes might appear
  content: [
    './assets/**/*.js',
    './assets/**/*.ts',
    './templates/**/*.html.twig',
    './templates/**/*.twig',
    // PHP files that generate class strings
    './src/**/*.php',
    // Config file with complete class strings for dynamic classes
    './config/tailwind-classes.php',
  ],

  // Class-based dark mode (toggle with JS/Stimulus)
  darkMode: 'class',

  theme: {
    extend: {
      fontFamily: {
        // Use system font stack — no custom fonts loaded
        sans: ['ui-sans-serif', 'system-ui', 'sans-serif'],
      },
      colors: {
        brand: {
          50:  '#f0f9ff',
          100: '#e0f2fe',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
        },
      },
    },
  },

  safelist: [
    // Dynamic status badge colors from database
    { pattern: /^(bg|text|border)-(red|yellow|green|blue)-(100|200|500|600|700)$/ },
  ],

  plugins: [
    // Prose plugin for rich text content from CMS
    require('@tailwindcss/typography'),
  ],
};

5. Twig-Integration: CSS und importmap einbinden

Im Twig-Basis-Template wird die Tailwind CSS Ausgabedatei über die AssetMapper-Funktion asset() eingebunden. Der AssetMapper ersetzt den Pfad zur Quelldatei automatisch durch den versionierten Pfad mit Content-Hash. Zusätzlich rendert der AssetMapper die importmap als Inline-Script-Tag im <head> – das ist nötig, damit der Browser die import-Statements in JavaScript-Dateien auflösen kann. Beides geschieht über Twig-Funktionen, die das Bundle mitbringt.

Ein wichtiger Aspekt beim Tailwind CSS Symfony AssetMapper: Die CSS-Datei muss vor dem importmap-Tag eingebunden werden, damit beim First-Paint kein FOUC (Flash of Unstyled Content) entsteht. Das Basis-Template sollte außerdem ein leeres {% block stylesheets %} und {% block javascripts %} enthalten, damit Kind-Templates seitenspezifische CSS oder JavaScript ergänzen können. Der AssetMapper bietet dafür den importmap-Twig-Helper, der alle importmap-Einträge als JSON-Script-Tag rendert und automatisch aktuell bleibt, wenn neue Pakete über php bin/console importmap:require hinzugefügt werden.

{# templates/base.html.twig — Symfony base template with AssetMapper + Tailwind CSS #}
<!DOCTYPE html>
<html lang="de" class="">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block title %}Mironsoft{% endblock %}</title>

  {# Link to Tailwind CSS output — AssetMapper adds content hash automatically #}
  <link rel="stylesheet" href="{ { asset('styles/app.css') } }">

  {% block stylesheets %}{% endblock %}

  {# importmap — maps bare module specifiers to URLs for native ES module imports #}
  { { importmap('app') } }
</head>
<body>
  {% block body %}{% endblock %}

  {% block javascripts %}{% endblock %}
</body>
</html>

6. Watch-Modus und Production-Build

Das Tailwind CSS Symfony-Entwicklungs-Workflow besteht aus zwei parallelen Prozessen: dem Symfony-Entwicklungsserver (symfony serve oder php -S localhost:8000 -t public/) und dem Tailwind CSS Watch-Prozess. Die Standalone CLI startet den Watch-Modus mit ./bin/tailwind -i assets/styles/app.css -o assets/styles/app.built.css --watch. Das --watch-Flag überwacht alle Quelldateien, die im content-Array der Konfiguration angegeben sind, und regeneriert die CSS-Ausgabe bei jeder Änderung. Die Ausgabedatei liegt im assets/-Verzeichnis, wird vom AssetMapper aufgenommen und steht nach einem Browser-Refresh sofort zur Verfügung.

Für den Produktionsbuild fügt die Standalone CLI die --minify-Option hinzu: ./bin/tailwind -i assets/styles/app.css -o assets/styles/app.built.css --minify. Danach folgt der AssetMapper-Schritt: php bin/console asset-map:compile kopiert alle Assets mit Content-Hash in das public/assets/-Verzeichnis und schreibt eine assets.json-Datei, die die Zuordnung von Quell- zu versioniertem Pfad enthält. Dieser Schritt ersetzt den Webpack-Build vollständig – ohne Node.js, ohne npm, ohne Webpack-Konfiguration. Die Deploy-Sequenz in einem Makefile oder CI-Skript ist damit deutlich kürzer als in einem klassischen Encore-Setup.

# Makefile — Tailwind CSS + Symfony AssetMapper build commands

# Development: watch mode for CSS (run in parallel with symfony serve)
.PHONY: watch
watch:
	./bin/tailwind -i assets/styles/app.css -o assets/styles/app.built.css --watch

# Production: minified CSS + asset compilation
.PHONY: build
build:
	./bin/tailwind -i assets/styles/app.css -o assets/styles/app.built.css --minify
	php bin/console asset-map:compile

# Download Tailwind Standalone CLI for the current platform
.PHONY: install-tailwind
install-tailwind:
	curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
	chmod +x tailwindcss-linux-x64
	mv tailwindcss-linux-x64 bin/tailwind

# Full deploy sequence
.PHONY: deploy
deploy: build
	php bin/console cache:clear --env=prod
	php bin/console cache:warmup --env=prod

7. JavaScript mit importmap und Stimulus

Der Symfony AssetMapper verwaltet JavaScript nicht nur als statische Dateien, sondern bietet eine vollständige Lösung für das JavaScript-Dependency-Management über importmap. Der Befehl php bin/console importmap:require @hotwired/stimulus lädt Stimulus herunter, trägt es in importmap.php ein und macht es über den Namen @hotwired/stimulus in JavaScript-Imports verfügbar. Dasselbe gilt für Alpine.js (importmap:require alpinejs), Chart.js oder jede andere JavaScript-Bibliothek, die als ESM-Modul verfügbar ist.

Im Zusammenspiel mit Tailwind CSS Symfony AssetMapper ist Stimulus der empfohlene Weg für JavaScript-Interaktivität: Stimulus Controller werden als separate JavaScript-Dateien im assets/controllers/-Verzeichnis geschrieben, vom AssetMapper registriert und über das @hotwired/stimulus-loading-Paket automatisch geladen. Das Naming-Convention-basierte Auto-Registrierung macht das Hinzufügen neuer Controller trivial. Alpine.js ist eine Alternative für einfachere Interaktionen direkt im Twig-Template – ähnlich wie in Hyvä Themes für Magento. Die Entscheidung zwischen Stimulus und Alpine.js hängt von der Komplexität der Interaktivität und der Präferenz des Teams ab.

8. Deployment: Asset-Fingerprinting und Cache-Busting

Das Deployment eines Tailwind CSS Symfony-Projekts mit AssetMapper ist deutlich einfacher als ein klassisches Encore-Deployment. Im Produktionsbuild führt asset-map:compile alle notwendigen Schritte durch: Es liest alle Assets aus den konfigurierten Pfaden, berechnet Content-Hashes, kopiert die Dateien mit Hash im Dateinamen in public/assets/ und schreibt eine Manifest-Datei. Twig verwendet dann die Manifest-Datei, um { { asset('styles/app.css') } } auf den korrekten versionierten Pfad aufzulösen. Das ist automatisches Cache-Busting ohne manuelles Versionierungsmanagement.

In einem CI/CD-Workflow mit GitHub Actions oder GitLab CI ist die Pipeline einfach: Checkout, Composer-Install, Tailwind-Binary-Download (oder aus dem Repository), Tailwind-Build, asset-map:compile, und dann der PHP-Applikation-Deploy. Da Node.js nicht mehr benötigt wird, entfällt die Node.js-Installation im CI-Agent vollständig. Das reduziert die Setup-Zeit und macht die Pipeline wartbarer. Das Tailwind Binary kann direkt im Git-Repository eingecheckt werden (die Binary ist etwa 35 MB), was die Abhängigkeit von einem externen Download in der Pipeline eliminiert.

9. AssetMapper vs. Webpack Encore: Direkter Vergleich

Die Wahl zwischen AssetMapper und Webpack Encore hängt von den Anforderungen des Projekts ab. Für die meisten Symfony-Projekte, die keine komplexen JavaScript-Bundles, Tree-Shaking oder module-spezifische Optimierungen benötigen, ist der AssetMapper die modernere und einfachere Wahl.

Die Tailwind CSS Symfony AssetMapper-Kombination ist für Projekte ideal, die hauptsächlich Server-seitiges Rendering mit Twig nutzen, JavaScript für einfache Interaktionen (Stimulus, Alpine.js) einsetzen und keine Legacy-Browser-Unterstützung benötigen. Webpack Encore bleibt die richtige Wahl für Single-Page-Applications mit React oder Vue, für Projekte, die IE-Unterstützung benötigen, oder für sehr komplexe JavaScript-Build-Anforderungen. Für den typischen Symfony-Monolithen mit primär serverseitigem Rendering ist der AssetMapper heute die bevorzugte Wahl des Symfony-Core-Teams.

10. Zusammenfassung

Das Tailwind CSS Symfony AssetMapper-Setup ist die moderne Alternative zu Webpack Encore für Symfony-Projekte: Kein Node.js im Produktionsbuild, kein komplexes Webpack-Konfigurationsfile, keine node_modules-Verwaltung. Die Tailwind CSS Standalone CLI verarbeitet CSS aus einer einzigen Binary heraus. Der AssetMapper übernimmt Content-Fingerprinting, Cache-Busting und importmap-Generierung für JavaScript. Twig bindet beides über { { asset() } } und { { importmap() } } ein. Das Ergebnis ist ein simples, wartbares Frontend-Setup, das in CI/CD-Pipelines deutlich weniger Konfiguration erfordert.

Die Grenzen des Setups: Ohne Webpack-Bundling gibt es kein Tree-Shaking für JavaScript-Bibliotheken und keine Transpilation für sehr alte Browser. Für Single-Page-Applications mit React oder Vue ist Webpack Encore oder Vite weiterhin die bessere Wahl. Für serverseitig gerendertes PHP mit Twig und moderater JavaScript-Komplexität ist der AssetMapper heute jedoch klar die bevorzugte Architektur – sie folgt der Philosophie von Symfony, Komplexität dort zu reduzieren, wo sie nicht notwendig ist, und stattdessen auf native Browser-Features zu setzen.

11. FAQ: Tailwind CSS Symfony AssetMapper