Von Encore zu AssetMapper: Symfony-Frontend-Migration in der Praxis

1. Warum überhaupt von Encore zu AssetMapper migrieren

Der Wechsel Encore zu AssetMapper ist in den meisten Fällen keine spontane Entscheidung, sondern das Ergebnis wachsenden Frusts über Build-Zeiten, Node-Version-Konflikte und die Komplexität einer Webpack-Konfiguration, die über Jahre gewachsen ist. Symfony AssetMapper verfolgt einen fundamental anderen Ansatz: Statt Module zu bündeln und zu transpilieren, liefert es JavaScript-Module direkt als ES-Module über HTTP/2 aus und nutzt native Browser-Fähigkeiten wie Importmaps, die inzwischen von allen relevanten Browsern unterstützt werden.

Der Umstieg Encore zu AssetMapper lohnt sich besonders für Projekte, die kein React, Vue oder TypeScript mit komplexer Typtransformation im Frontend einsetzen, sondern auf Stimulus, Vanilla-JS und Tailwind setzen. In diesem Szenario bringt Webpack praktisch keinen Mehrwert mehr, sondern nur zusätzliche Build-Zeit und eine weitere Werkzeugkette, die gepflegt werden muss. Projekte mit echten Build-Anforderungen wie JSX-Kompilierung oder komplexem Tree-Shaking über npm-Pakete mit CommonJS-Exporten profitieren dagegen weiterhin von Encore oder einem dedizierten Vite-Setup.

Wichtig für die Entscheidung Encore zu AssetMapper: Die Migration muss nicht in einem einzigen Schritt erfolgen. Beide Systeme können während der Übergangsphase parallel im selben Projekt existieren, was das Risiko eines Big-Bang-Umzugs erheblich reduziert.

2. Bestandsaufnahme: was Encore aktuell übernimmt

Bevor die Migration Encore zu AssetMapper beginnt, lohnt sich eine ehrliche Bestandsaufnahme der webpack.config.js. Die meisten Projekte nutzen Encore für vier Dinge: Bündelung mehrerer JavaScript-Dateien zu Entrypoints, Kompilierung von Sass oder Less zu CSS, Transpilierung von modernem JavaScript für ältere Browser über Babel, sowie Versionierung und Cache-Busting der ausgelieferten Dateien über Hashes im Dateinamen.

AssetMapper deckt Versionierung und Cache-Busting nativ ab, ebenso das reine Ausliefern von JavaScript-Modulen ohne Transpilierung. Was AssetMapper nicht mitbringt, ist eine Babel-artige Transpilierung für sehr alte Browser und keine native Sass-Kompilierung. Diese Lücken müssen entweder über externe CLI-Tools geschlossen werden, oder die Anforderung entfällt, weil moderne Browser die benötigten JavaScript-Features bereits nativ unterstützen.

# Audit: what does the existing Encore config actually do?
grep -E "addEntry|enableSassLoader|enablePostCssLoader|configureBabel" webpack.config.js

# List all npm packages actually imported in JS entrypoints
grep -rhoE "from ['\"][a-zA-Z@][^'\"]*['\"]" assets/ | sort -u

3. AssetMapper installieren, Encore vorerst behalten

Der sichere Einstieg in Encore zu AssetMapper ist die parallele Installation. AssetMapper wird als zusätzliches Bundle installiert, während Encore weiterhin für die bestehenden Entrypoints zuständig bleibt. Symfony erlaubt es, Templates weiterhin mit encore_entry_script_tags() für alte Bereiche zu rendern und gleichzeitig importmap() für bereits migrierte Templates zu nutzen. Beide Funktionen können im selben Layout nebeneinander existieren, solange sie nicht dieselben globalen Variablen oder DOM-IDs beanspruchen.

Diese Koexistenz ist der Kern einer risikoarmen Migrationsstrategie Encore zu AssetMapper: Statt alle Seiten an einem Tag umzustellen, wird Seite für Seite, Bereich für Bereich migriert, mit der Möglichkeit, jederzeit zurückzurudern, falls ein migriertes Modul unerwartete Probleme verursacht.

# Install AssetMapper alongside the existing Encore setup
composer require symfony/asset-mapper symfony/asset symfony/stimulus-bundle

# AssetMapper needs its own directory structure
bin/console debug:asset-map

4. Entrypoints Stück für Stück ersetzen

Jeder Encore-Entrypoint entspricht in AssetMapper einer eigenen Importmap-Einstiegsdatei, die über bin/console importmap:require registriert wird. Der Unterschied: Statt eines gebündelten Bundles mit allen Abhängigkeiten inline lädt der Browser jedes Modul als separate Datei nach, adressiert über die generierte Importmap im <head>. Für die Migration Encore zu AssetMapper bedeutet das, jede import-Anweisung im bestehenden JavaScript-Code auf Kompatibilität mit ES-Modulen zu prüfen, da AssetMapper kein CommonJS unterstützt.

In der Praxis läuft die Migration eines Entrypoints so ab: Zunächst wird die Datei unverändert nach assets/ kopiert, dann werden alle require()-Aufrufe zu import-Statements umgeschrieben, und abschließend wird das Template von encore_entry_script_tags() auf importmap() umgestellt. Bei Stimulus-Controllern übernimmt symfony/stimulus-bundle die automatische Registrierung, sodass in den meisten Fällen kein manueller Import-Code mehr nötig ist.

// Before (Encore, CommonJS-style require still common in older configs)
const Sortable = require('sortablejs');

// After (AssetMapper, native ES module import)
import Sortable from 'sortablejs';

// Stimulus controllers are auto-discovered via symfony/stimulus-bundle
// assets/controllers.json lists every registered controller and its enabled state

5. npm-Pakete auf Importmap umziehen

Der zeitintensivste Teil der Migration Encore zu AssetMapper ist meist das Umziehen von npm-Paketen. AssetMapper lädt Pakete standardmäßig über jsdelivr.com als CDN-Proxy für npm-Module herunter und speichert sie lokal im vendor-Verzeichnis der Assets, sodass zur Laufzeit keine externe Anfrage mehr nötig ist. Der Befehl importmap:require übernimmt Auflösung, Download und Eintragung in importmap.php automatisch.

Nicht jedes npm-Paket eignet sich für diesen Weg. Pakete, die intern auf CommonJS-require-Aufrufe oder Node.js-spezifische APIs wie fs oder path angewiesen sind, funktionieren nicht als reines ES-Modul im Browser. Für die Migration Encore zu AssetMapper bedeutet das: Bibliotheken vorab auf ihre ESM-Kompatibilität prüfen, idealerweise über die "module"- oder "exports"-Felder in der jeweiligen package.json.

# Migrate npm packages one by one to the importmap
bin/console importmap:require sortablejs
bin/console importmap:require chart.js
bin/console importmap:require @hotwired/stimulus

# Verify the resulting entries
cat importmap.php

6. Sass ablösen: PostCSS und Tailwind statt Webpack-Loader

Da AssetMapper keinen Sass-Compiler mitbringt, ist die CSS-Seite der Migration Encore zu AssetMapper häufig der Teil mit dem größten strukturellen Eingriff. Projekte, die bereits Tailwind CSS nutzen, haben es einfach: Der eigenständige Tailwind-CLI-Build läuft komplett unabhängig von Encore oder AssetMapper und muss nur im package.json-Skript weiterhin ausgeführt werden. Projekte mit umfangreichen Sass-Strukturen mit Mixins und Variablen müssen entweder auf natives CSS mit Custom Properties umstellen oder einen eigenständigen Sass-Compiler außerhalb von Symfony betreiben.

Ein pragmatischer Zwischenschritt bei der Migration Encore zu AssetMapper: Der Sass-Compiler bleibt als eigenständiges npm-Skript bestehen und erzeugt weiterhin eine kompilierte CSS-Datei, die anschließend, wie jede andere statische Datei, über AssetMapper ausgeliefert wird. AssetMapper übernimmt in diesem Fall nur die Auslieferung und Versionierung, nicht die eigentliche Sass-Kompilierung.

7. Stimulus-Controller ohne Build-Schritt betreiben

Stimulus-Controller sind der Idealfall für Encore zu AssetMapper, weil sie in aller Regel bereits als reine ES-Module geschrieben sind und keine komplexe Build-Transformation benötigen. Nach der Migration registriert symfony/stimulus-bundle jeden Controller automatisch über die Datei assets/controllers.json, die Encore-Projekte in dieser Form meist gar nicht kannten, weil Encore die Registrierung über bootstrap.js und Webpacks Context-Import-Mechanismus löste.

Für Teams, die bislang require.context() zum automatischen Einsammeln aller Controller-Dateien genutzt haben, ist der Umstieg Encore zu AssetMapper tatsächlich eine Verbesserung: Die explizite Liste in controllers.json macht sichtbar, welche Controller aktiv sind, und erlaubt es, einzelne Controller pro Umgebung gezielt zu deaktivieren, ohne Code zu löschen.

{
  "controllers": {
    "@symfony/ux-dropzone": {
      "dropzone": { "enabled": true, "fetch": "eager" }
    },
    "app": {
      "sortable": {
        "enabled": true,
        "fetch": "lazy",
        "autoimport": { "sortablejs/modular/sortable.core.esm.js": true }
      }
    }
  },
  "entrypoints": []
}

8. Produktions-Deployment ohne Node.js

Ein oft unterschätzter Vorteil der Migration Encore zu AssetMapper: Sobald keine Sass-Kompilierung mehr benötigt wird, entfällt Node.js als Build-Abhängigkeit im Produktions-Deployment vollständig. bin/console asset-map:compile übernimmt die Versionierung und das Kopieren aller Assets in public/assets, komplett mit PHP, ohne dass ein npm install oder yarn build im Deployment-Skript ausgeführt werden muss.

Das reduziert die Angriffsfläche für Supply-Chain-Probleme über npm-Abhängigkeiten im Produktions-Build erheblich, weil zur Laufzeit nur noch die tatsächlich genutzten, vorab heruntergeladenen Vendor-Dateien im Repository liegen. Für Deployment-Pipelines mit Deployer oder ähnlichen Tools verkürzt sich der Build-Schritt Encore zu AssetMapper spürbar, da der zeitintensive Webpack-Kompilierungsschritt komplett entfällt.

Ein weiterer Aspekt, der bei der Migration Encore zu AssetMapper oft unterschätzt wird, ist die Auswirkung auf lokale Entwicklungszeiten. Ohne Webpack-Dev-Server entfällt auch das anfängliche Kompilieren beim ersten Start des Entwicklungsservers, jede Änderung an einer JavaScript-Datei wird beim nächsten Browser-Reload direkt sichtbar, ohne auf einen Rebuild zu warten. Für Teams mit vielen kleinen Frontend-Iterationen summiert sich diese eingesparte Wartezeit über den Arbeitstag spürbar.

9. Encore und AssetMapper im direkten Vergleich

Die Entscheidung zwischen beiden Systemen hängt stark vom Umfang der bestehenden Frontend-Anforderungen ab. Die folgende Übersicht fasst die wichtigsten Unterschiede zusammen, die bei der Migration Encore zu AssetMapper berücksichtigt werden sollten.

Für React- oder Vue-lastige Frontends mit JSX-Kompilierung bleibt Encore oder ein dediziertes Vite-Setup die passendere Wahl. Für Stimulus-basierte, serverseitig gerenderte Symfony-Anwendungen mit Tailwind ist Encore zu AssetMapper in den meisten Fällen ein klarer Gewinn an Einfachheit und Build-Geschwindigkeit.

10. Zusammenfassung

Die Migration Encore zu AssetMapper ist kein Rewrite, sondern ein schrittweiser Umzug, der während der Übergangszeit auch parallel zu Encore laufen kann. Entrypoints werden einzeln umgestellt, npm-Pakete auf ESM-Kompatibilität geprüft und über die Importmap eingebunden, und Sass wird entweder durch natives CSS mit Tailwind ersetzt oder als eigenständiges Build-Skript weitergeführt. Stimulus-Controller profitieren am stärksten von der Migration, weil ihre Registrierung über controllers.json transparenter wird als über Webpacks Context-Import.

Für Projekte ohne JSX- oder TypeScript-Transformationsbedarf entfällt am Ende der Migration Encore zu AssetMapper Node.js als Produktions-Build-Abhängigkeit vollständig, was Deployment-Zeiten verkürzt und die Angriffsfläche für Supply-Chain-Risiken reduziert. Wer noch komplexe Sass-Strukturen oder JSX-Kompilierung benötigt, sollte Encore für diese Teile vorerst behalten und nur die einfacheren Bereiche migrieren.

11. FAQ: Encore zu AssetMapper