TYPO3 _assets: So migrieren Sie typo3conf/ext Assets in Composer

Die Umstellung eines TYPO3-Projekts auf Composer verändert nicht nur die Art, wie Erweiterungen installiert werden. Sie verändert auch, wie öffentliche Erweiterungsressourcen wie CSS, JavaScript, Bilder und Schriftarten für das Web bereitgestellt werden.

Wenn Ihr Projekt noch fest kodierte Pfade wie diese enthält:

 

/typo3conf/ext/site_package/Resources/Public/...

 

sollten Sie diese bei der Migration zu einer modernen Composer-basierten TYPO3-Installation überprüfen.

Im Composer-Modus werden TYPO3-Extensions außerhalb der öffentlichen Web-Root installiert. Ihre öffentlichen Ressourcen werden über public/_assets/ bereitgestellt, während Dateien wie PHP-Klassen, Konfigurationen und Vorlagen vor direktem HTTP-Zugriff geschützt bleiben. 

TYPO3 v12 erfordert typo3/cms-composer-installers v5, wodurch diese Struktur Teil der standardmäßigen Composer-Installation wird.

Die gute Nachricht: Normalerweise sollten Sie alte URLs nicht durch fest kodierte _assets-URLs ersetzen. Verwenden Sie stattdessen die Ressourcen-APIs von TYPO3, EXT:-Verweise, relative Pfade oder Ihr Frontend-Build-System.

Diese Anleitung zeigt Ihnen genau, wie die Migration funktioniert.

Was ist _assets in TYPO3?

public/_assets/ enthält Symlinks zu den Resources/Public/-Verzeichnissen von per Composer installierten TYPO3 extensions.

Zum Beispiel:

 

packages/site_package/
└── Resources/
    └── Public/
        ├── Css/
        ├── JavaScript/
        ├── Images/
        └── Fonts/

 

Composer/TYPO3 stellt diese öffentlichen Ressourcen über Folgendes bereit:

public/_assets/<generated-hash>/

Der Hash hilft dabei, den Namen der Erweiterung und den Composer-Pfad nicht offenzulegen. Der genaue Hash-Mechanismus ist jedoch ein Implementierungsdetail und kann sich in zukünftigen TYPO3-Major-Versionen ändern.

Daher: Erstellen Sie Ihre Anwendung nicht mit einer hart codierten URL _assets/<hash>/....

Warum hat TYPO3 von typo3conf/ext zu _assets gewechselt?

Der Hauptgrund ist Sicherheit und eine sauberere Composer-Architektur.

In älteren Installationen konnte eine Erweiterung direkt unter folgendem Pfad erreichbar sein:

 

public/typo3conf/ext/

 

Das bedeutete, dass der Webserver potenziell Dateien ausliefern konnte, die nie für die Öffentlichkeit bestimmt waren.

Moderne Composer-Installationen platzieren Erweiterungspakete außerhalb des öffentlichen Webroots, typischerweise unter vendor/ oder einem lokalen packages/-Verzeichnis. Nur das Verzeichnis Resources/Public/ der Erweiterung wird für den Browser freigegeben.

Die grundlegende Architektur sieht nun so aus:

 

Composer-Erweiterung
      │
      ├── PHP
      ├── Konfiguration
      ├── Templates
      └── Resources/Public
                    │
                    ▼
              public/_assets/

 

Dadurch entsteht eine deutlich bessere Trennung zwischen Anwendungscode und öffentlichen Assets.

typo3conf/ext vs. Composer _assets

Älterer Ansatz	Composer-basiertes TYPO3
public/typo3conf/ext/	vendor/ oder packages/
Erweiterungscode öffentlich abgelegt	Erweiterungscode außerhalb des Webroots
Assets direkt referenziert	Öffentliche Assets über _assets bereitgestellt
Hart codierte Erweiterungspfade üblich	TYPO3-Resource-APIs bevorzugt
Höheres Risiko, interne Dateien offenzulegen	Bessere Trennung von öffentlich und privat

Die aktuelle Dokumentation zur Verzeichnisstruktur von TYPO3 bestätigt, dass public/_assets/ Symlinks zu den Erweiterungsverzeichnissen Resources/Public/ enthält und dass typo3conf/ext/ in modernen Composer-Projekten nicht mehr verwendet wird.

Schritt 1: Alte Verweise auf typo3conf/ext finden

Bevor Sie Code ändern, durchsuchen Sie Ihr gesamtes Projekt nach:

 

typo3conf/ext/

 

Prüfen Sie:

• Fluid-Templates
• CSS
• SCSS
• JavaScript
• TypeScript
• PHP
• TypoScript
• TSconfig
• RTE-Konfiguration
• YAML
• JSON
• Frontend-Build-Konfiguration
• eigene Skripte

TYPO3 selbst empfiehlt, den Erweiterungscode während der Migration nach alten typo3conf/ext/-Verweisen zu durchsuchen.

Eine einfache projektweite Suche kann die meisten Migrationskandidaten aufdecken:

 

grep -R "typo3conf/ext/" .

 

Ihr Ziel ist es nicht, jede Vorkommnis blind zu ersetzen. Ermitteln Sie zuerst, um welche Art von Pfad es sich handelt.

Schritt 2: Öffentliche Assets in Resources/Public belassen

Öffentliche Erweiterungs-Assets sollten sich innerhalb von Folgendem befinden:

 

Resources/Public/

 

Typische Struktur:

 

Resources/Public/
├── Css/
├── JavaScript/
├── Images/
├── Fonts/
└── Icons/

 

TYPO3 definiert Resources/Public ausdrücklich für Dateien, die vom Webserver ausgeliefert werden sollen, wie CSS, JavaScript, Bilder und Schriftarten.

Private Ressourcen wie Templates, Konfiguration und Lokalisierungsdateien sollten privat bleiben.

CSS-Asset-Pfade migrieren

Eines der häufigsten Migrationsprobleme ist eine hart codierte CSS-URL.

Alter Ansatz

 

.CssClass {
    background-image: url("/typo3conf/ext/site_package/Resources/Public/Images/TheImage.jpeg");
}

 

Dieser Pfad funktioniert nicht korrekt, sobald die Erweiterung über die moderne Composer-Struktur installiert wird.

Beste Option: relative Pfade verwenden

Wenn CSS und Bild zur gleichen Erweiterung gehören, verwenden Sie eine relative URL:

 

.CssClass {
    background-image: url("../Images/TheImage.jpeg");
}

 

Dies ist der bevorzugte Ansatz für Ressourcen innerhalb derselben Erweiterung. Die TYPO3-Migrationsdokumentation empfiehlt für diesen Fall ausdrücklich relative Links.

Dies vermeiden

 

background-image: url("/_assets/<hash>/Images/TheImage.jpeg");

 

Auch wenn eine gehashte _assets-URL funktionieren kann, koppelt sie Ihr CSS an das interne Asset-Mapping von TYPO3.

Was ist, wenn CSS ein Asset aus einer anderen Erweiterung referenziert?

Das ist ein komplexerer Fall.

Zum Beispiel:

Erweiterung A

 

└── Resources/Public/Css/style.css

 

Erweiterung B

 

└── Resources/Public/Images/logo.svg

 

CSS kann TYPO3s EXT:-Syntax im Browser nicht direkt und bequem verwenden.

Bessere Optionen sind unter anderem:

1. Gemeinsam genutzte Assets in einem zentralen Sitepackage bündeln.
2. Einen Frontend-Asset-Bundler wie Vite, webpack, Gulp oder Encore verwenden.
3. Die Asset-URL über Fluid, PHP oder TypoScript erzeugen und an das Frontend übergeben.
4. Eine dedizierte Route oder PSR-15-Middleware für spezielle dynamische Asset-Anforderungen verwenden.

TYPO3 empfiehlt, gemeinsam genutzte Assets zu zentralisieren oder bei Bedarf einen Bundler zu verwenden.

JavaScript-Asset-Pfade migrieren

JavaScript enthält oft versteckte Asset-Abhängigkeiten.

Zum Beispiel kann eine Kartenbibliothek Folgendes enthalten:

 

const icon = L.icon({
    iconUrl: '/typo3conf/ext/site_package/Resources/Public/Icons/Map/marker.svg',
    shadowUrl: '/typo3conf/ext/site_package/Resources/Public/Icons/Map/shadow.svg'
});

 

Anstatt den alten Pfad hart zu codieren, lassen Sie TYPO3 die Ressource auflösen.

Empfohlener Ansatz: URLs über HTML übergeben

In Fluid:

 

<div
    id="map"
    data-icon="{f:uri.resource(path: 'Icons/Map/marker.svg')}"
    data-shadow="{f:uri.resource(path: 'Icons/Map/shadow.svg')}"
></div>

 

Dann kann JavaScript die generierten URLs verwenden:

const mapElement = document.getElementById('map');

 

const icon = L.icon({
    iconUrl: mapElement.dataset.icon,
    shadowUrl: mapElement.dataset.shadow
});

 

Dieser Ansatz hält die TYPO3-spezifische Pfadauflösung in TYPO3 und macht Ihr JavaScript unabhängig von _assets.

Die aktuelle Resources-API von TYPO3 empfiehlt diese Art der Ressourcenauflösung anstelle direkter Verweise auf _assets.

Fluid-Templates migrieren

Fluid-Templates sollten TYPO3s Ressourcenbehandlung anstelle hart codierter typo3conf/ext-URLs verwenden.

Alt

 

<img src="/typo3conf/ext/site_package/Resources/Public/Images/logo.svg" alt="Logo">

 

Empfohlen

 

<img
    src="{f:uri.resource(path: 'Images/logo.svg')}"
    alt="Logo"
>

 

Zum Beispiel für einen SVG-Sprite:

 

<svg>
    <use href="{f:uri.resource(path: 'Images/icons.svg')}#symbol"></use>
</svg>

 

Sie können bei Bedarf auch explizit eine Erweiterung mit EXT: referenzieren:

 

{f:uri.resource(
    path: 'EXT:site_package/Resources/Public/Images/logo.svg'
)}

 

Die Resources-API von TYPO3 identifiziert f:uri.resource als den Standard-Mechanismus in Fluid zur Auflösung öffentlicher Erweiterungsressourcen.

Best Practice

Lassen Sie Fluid/TYPO3 die öffentliche URL erzeugen.

Versuchen Sie nicht, den _assets-Hash selbst zu berechnen.

PHP-Asset-Referenzen migrieren

PHP kann entweder einen Dateisystempfad oder eine öffentliche Web-URL benötigen. Das sind zwei verschiedene Dinge.

Für einen serverseitigen Dateipfad TYPO3 unterstützt die EXT:-Syntax mit seinen Resource/Path-APIs:

 

$absoluteFilePath = GeneralUtility::getFileAbsFileName(
    'EXT:site_package/Resources/Public/Images/logo.png'
);

 

Für eine öffentliche URL verwenden Sie eine API, die für die Auflösung eines Webpfads gedacht ist, statt manuell zusammenzuketten:

 

TYPO3_SITE_URL + /_assets/<hash>/...

 

Die aktuelle Resources-API von TYPO3 unterscheidet ausdrücklich zwischen serverseitigen Ressourcenpfaden und öffentlichen Ressourcen-URLs.

Merken Sie sich

Dateisystempfad ≠ öffentliche URL

Diese Unterscheidung verhindert viele Composer-Migrationsfehler.

TypoScript-Asset-Referenzen migrieren

TypoScript enthält häufig Verweise auf CSS, JavaScript, Schriftarten und Bilder.

Verwenden Sie EXT:-Verweise statt des alten Dateisystempfads.

Zum Beispiel:

 

page.meta {
    og:image.cObject = TEXT
    og:image.cObject {
        typolink {
            parameter.cObject = IMG_RESOURCE
            parameter.cObject.file =
                EXT:site_package/Resources/Public/Images/opengraph.png
            returnLast = url
            forceAbsoluteUrl = 1
        }
    }
}

 

Dasselbe Prinzip gilt beim Definieren von Ressourcen wie Schriftarten oder anderen öffentlichen Assets.

Die TYPO3-Migrationsdokumentation empfiehlt die Notation EXT:my_extension/Resources/Public/..., wo sie unterstützt wird.

TSconfig migrieren

Alte TSconfig-Verweise können so aussehen:

 

<INCLUDE_TYPOSCRIPT: source="FILE:typo3conf/ext/site/Configuration/TSconfig/User/name.tsconfig">

 

Verwenden Sie stattdessen die erweiterungsbewusste Syntax:

 

<INCLUDE_TYPOSCRIPT:    source="FILE:EXT:site_package/Configuration/TSconfig/User/name.tsconfig">

 

Dadurch entfällt die Abhängigkeit vom alten typo3conf/ext-Speicherort.

RTE-Konfiguration migrieren

Die RTE-Konfiguration ist ein weiterer leicht zu übersehender Ort.

Alt

 

editor:
  config:
    contentCss: '/typo3conf/ext/site_package/Resources/Public/Css/rte.css'

 

Empfohlen

 

editor:
  config:
    contentCss: 'EXT:site_package/Resources/Public/Css/rte.css'

 

Wenn Sie ein TYPO3-Projekt migrieren, nehmen Sie die RTE-Konfiguration in Ihre projektweite Suche nach typo3conf/ext auf.

Was ist mit statischen Dateien?

Nicht jede Datei gehört in Resources/Public.

Wenn eine Datei direkt unterhalb des öffentlichen Webroots eine vorhersehbare URL benötigt, etwa eine statische Ressource auf Projektebene, benötigen Sie möglicherweise ein dediziertes öffentliches Verzeichnis oder einen anderen TYPO3-Mechanismus.

Für dynamische Inhalte sollten Sie Folgendes in Betracht ziehen:

• PSR-15-Middleware
• dynamische Routen
• einen dedizierten öffentlichen Endpunkt
• ein öffentliches Verzeichnis auf Projektebene

Die TYPO3-Migrationsdokumentation empfiehlt ausdrücklich dynamische Routen, Middleware oder benutzerdefinierte öffentliche Verzeichnisse für statische Links, die nicht den normalen Mechanismus für Erweiterungsressourcen verwenden können.

Denken Sie außerdem daran:

Platzieren Sie zur Laufzeit erzeugte Dateien nicht in Resources/Public.

Dieses Verzeichnis ist für statische Erweiterungs-Assets vorgesehen.

Verwalten Sie public/_assets nicht manuell

Dies ist eine der wichtigsten Regeln.

Das Verzeichnis _assets wird im Rahmen des Composer/TYPO3-Setups generiert und verwaltet.

Tun Sie Folgendes nicht:

• seine Verzeichnisse manuell umbenennen
• seine Symlinks manuell ersetzen
• Inhalte von _assets für die Produktion als normale Dateien einchecken
• die Anwendungslogik auf den generierten Hash aufbauen

TYPO3 empfiehlt, dass _assets reproduzierbar bleibt und seine Symlinks über Composer neu erstellt werden können. Ein composer dumpautoload kann fehlende Public-Asset-Links nach dem Hinzufügen von Ressourcen neu erzeugen.

Wie finde ich die _assets-URL?

Wenn Sie das generierte Asset-Mapping wirklich prüfen müssen, bietet TYPO3 Console:

 

vendor/bin/typo3 frontend:asseturl

 

Dies kann helfen, den Hash des öffentlichen Ressourcenverzeichnisses für installierte Erweiterungen zu ermitteln.

Verwenden Sie dies jedoch vor allem für Debugging oder Sonderfälle und nicht als normale Strategie für Asset-Verweise. TYPO3 empfiehlt, direkte _assets-Verweise zu vermeiden, weil der Hash-Mechanismus ein Implementierungsdetail ist.

TYPO3 _assets-Migrations-Checkliste

Bevor Sie Ihre Migration abschließen, prüfen Sie:

• Das gesamte Projekt nach typo3conf/ext/ durchsuchen.
• Öffentliche Erweiterungs-Assets in Resources/Public/ verschieben.
• Hart codierte Fluid-URLs durch f:uri.resource ersetzen.
• In TypoScript und unterstützten Konfigurationen EXT:-Verweise verwenden.
• Alte CSS-Pfade durch relative URLs ersetzen, wenn die Assets zur gleichen Erweiterung gehören.
• TYPO3-generierte URLs bei Bedarf über Data-Attribute an JavaScript übergeben.
• PHP-Dateisystempfade getrennt von öffentlichen URLs prüfen.
• TSconfig- und RTE-Konfiguration prüfen.
• Frontend-Build-Pipelines überprüfen.
• Vermeiden Sie die feste Einbindung von _assets/<hash>/.
• Symlinks in _assets nicht manuell verwalten.
• Bei Bedarf composer dump-autoload ausführen.
• Caches leeren und das Frontend testen.
• CSS, JavaScript, Bilder, Schriftarten, SVGs und Downloads testen.
• Die Produktionsbereitstellung mit einer sauberen Composer-Installation testen.

Häufige TYPO3 _assets-Migrationsfehler

Jeden alten Pfad durch _assets ersetzen

Wandeln Sie nicht einfach:

 

/typo3conf/ext/site/Resources/Public/logo.svg

 

in:

 

/_assets/<hash>/logo.svg

 

Den Hash selbst berechnen

Der Hash ist ein Implementierungsdetail.

Dateisystempfade als Browser-URLs verwenden

Ein serverseitiger Pfad und eine öffentliche URL sind nicht austauschbar.

Frontend-Build-Tools vergessen

Webpack, Vite, Encore, Gulp und ähnliche Pipelines können weiterhin alte Ausgabepfade enthalten.

_assets manuell bearbeiten

Lassen Sie Composer/TYPO3 die Symlinks erstellen.

Fazit

Der Wechsel von typo3conf/ext zu Composer-basiertem Erweiterungs-Handling ist mehr als nur eine Pfadänderung. Es ist ein Schritt hin zu einer saubereren Trennung zwischen privatem Erweiterungscode und öffentlichen Web-Assets.

Die wichtigste Regel ist einfach:

Migrieren Sie alte Pfade nicht, indem Sie _assets-URLs hart codieren. Migrieren Sie die Art und Weise, wie Ihre Anwendung Assets referenziert.

Verwenden Sie:

• Resources/Public/ für statische öffentliche Erweiterungs-Assets
• f:uri.resource in Fluid
• EXT:-Notation, wo unterstützt
• relative Pfade für Assets innerhalb derselben Erweiterung
• TYPO3-Resource-APIs für PHP
• Data-Attribute für JavaScript, wenn URLs in Frontend-Code übergeben werden müssen
• eine zentrale Asset-Strategie oder einen Bundler für gemeinsam genutzte Assets

Wenn diese Muster einmal umgesetzt sind, wird Ihr TYPO3-Projekt sicherer, Composer-freundlicher und über zukünftige TYPO3-Upgrades hinweg leichter zu warten sein.

Resources/Public/