Ein Bundle anlegen
Jede Erweiterung für Vendority ist ein Symfony-Bundle mit eigenem Frontend, das der Core beim Start nachlädt. Sie legen das Bundle „acme“ an, auf dem alle weiteren Tutorials aufbauen.
Was Sie bauen
Das Bundle acme unter dev/vendority/acme-bundle. Symfony kennt es als Plugin, und sein Frontend meldet sich in der Browserkonsole.
Voraussetzungen
- Eine lokale Vendority-Installation mit Docker, erreichbar unter
http://app.vendority.local - Node.js und npm auf Ihrem Rechner
- Ein GitHub-Token mit dem Recht
read:packages, um@vendority/corezu installieren - Ein Token für die Paketquelle von Hugeicons Pro (
npm.hugeicons.com), um die Symbole zu installieren
Schritt 1 von 7
Das Verzeichnis und die composer.json anlegen
Composer findet jedes Paket unter dev/vendority von selbst. Ihr Bundle braucht dort nur ein eigenes Verzeichnis mit einer composer.json.
Terminal
Befehl
mkdir -p dev/vendority/acme-bundle/src/DependencyInjection dev/vendority/acme-bundle/config/packages dev/vendority/acme-bundle/translationscomposer.json
Neue Datei
{
"name": "vendority/acme-bundle",
"description": "Acme – Beispiel-Bundle für Vendority",
"type": "symfony-bundle",
"prefer-stable": true,
"minimum-stability": "dev",
"require": {
"php": "~8.4.0",
"vendority/core": "*"
},
"autoload": {
"psr-4": {
"Vendority\\Bundle\\Acme\\": "src/"
}
}
}-
1
Den Befehl führen Sie im Projektverzeichnis Ihrer Installation aus, wie alle Befehle in diesem Tutorial.
-
2
Die
composer.jsondes Projekts bindet über das Repository./dev/*/*jedes Paket unterdev/ein und verlinkt es nachvendor/. Änderungen am Code wirken deshalb sofort. -
3
Der Namensraum
Vendority\Bundle\Acme\zeigt aufsrc/. Er muss mitVendoritybeginnen, denn nur bei solchen Bundles lädt der Coreconfig/services.yaml,config/packages/undconfig/routes/automatisch. -
4
vendority/coresteht als Abhängigkeit drin, weil das Bundle auf den Basisklassen des Core aufbaut.
Schritt 2 von 7
Die Bundle-Klasse und die Extension schreiben
Die Bundle-Klasse meldet das Bundle beim Core als Plugin an. Die Extension lädt seine Services.
src/VendorityAcmeBundle.php
Neue Datei
<?php
declare(strict_types=1);
namespace Vendority\Bundle\Acme;
use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
use Vendority\Bundle\Acme\DependencyInjection\VendorityAcmeExtension;
use Vendority\Bundle\Core\Plugin\AbstractVendorityPluginBundle;
final class VendorityAcmeBundle extends AbstractVendorityPluginBundle
{
public function getContainerExtension(): ?ExtensionInterface
{
return new VendorityAcmeExtension();
}
public function getPluginName(): string
{
return 'acme';
}
public function getViteBuildDirectory(): string
{
return 'bundles/vendorityacme/build';
}
}src/DependencyInjection/VendorityAcmeExtension.php
Neue Datei
<?php
declare(strict_types=1);
namespace Vendority\Bundle\Acme\DependencyInjection;
use Vendority\Bundle\Core\Plugin\AbstractVendorityPluginExtension;
final class VendorityAcmeExtension extends AbstractVendorityPluginExtension
{
protected function getPluginName(): string
{
return 'acme';
}
protected function getViteBuildDirectory(): string
{
return 'bundles/vendorityacme/build';
}
protected function getConfigPath(): string
{
return __DIR__ . '/../../config';
}
}-
1
AbstractVendorityPluginBundleversieht das Bundle mit dem Tagvendority.plugin. Über diesen Tag findet der Core alle Plugins und bindet ihr Frontend ein. -
2
getPluginName()liefert den Kurznamenacme. Derselbe Name steht später in der Vite-Konfiguration und inpentatrion_vite.yaml. -
3
getViteBuildDirectory()nennt den öffentlichen Pfad des gebauten Frontends. Symfony veröffentlicht den Ordnerpublic/des Bundles unterpublic/bundles/vendorityacme/; der Name ergibt sich aus der KlasseVendorityAcmeBundle. -
4
getContainerExtension()gibt Ihre Extension zurück. Ohne die Methode legt Symfony für das Bundle eine eigene Extension an, und Ihre wird nie geladen. -
5
AbstractVendorityPluginExtensionlädtservices.yamlaus dem Ordner, dengetConfigPath()nennt. Die beiden anderen Methoden sind in der Basisklasse abstrakt und müssen deshalb vorhanden sein.
Schritt 3 von 7
Konfiguration und Übersetzungen anlegen
Für den Anfang genügen zwei YAML-Dateien: eine für die Services, eine für den Build des Frontends. Dazu kommen leere Dateien für die Übersetzungen.
config/services.yaml
Neue Datei
services:
_defaults:
autowire: true
autoconfigure: trueconfig/packages/pentatrion_vite.yaml
Neue Datei
pentatrion_vite:
configs:
acme:
build_directory: bundles/vendorityacme/buildTerminal
Befehl
touch dev/vendority/acme-bundle/translations/messages.de.yaml dev/vendority/acme-bundle/translations/messages.en.yaml dev/vendority/acme-bundle/translations/messages.fr.yaml dev/vendority/acme-bundle/translations/messages.it.yaml-
1
In
services.yamlregistrieren Sie später jeden Service, jeden Controller und jede Berechtigung Ihres Bundles. Der Core durchsucht keine Ordner nach Klassen; was hier nicht steht, ist kein Service. -
2
autoconfigure: truesorgt dafür, dass Symfony registrierte Klassen, die eine Schnittstelle des Core implementieren, automatisch mit dem passenden Tag versieht. -
3
pentatrion_vite.yamlverbindet den Namenacmemit dem Build-Verzeichnis. Daran erkennt der Core auch, ob gerade ein Vite-Dev-Server für das Bundle läuft. -
4
Jede Datei unter
config/packages/lädt der Kernel automatisch, Routen unterconfig/routes/ebenso. Die erste Route legen Sie im Tutorial „Einen API-Endpunkt anlegen“ an. -
5
Die Texte Ihres Bundles stehen in
translations/messages.<sprache>.yaml, je eine Datei für Deutsch, Englisch, Französisch und Italienisch. Das Frontend lädt sie nach der Anmeldung vom Server. Fehlt ein Schlüssel in einer Datei, fehlt der Text in dieser Sprache.
Schritt 4 von 7
Die Build-Werkzeuge für das Frontend einrichten
Das Frontend ist eine kleine Vite-Anwendung im Ordner assets. Der Core lädt sie beim Start per Module Federation nach.
Terminal
Befehl
mkdir -p dev/vendority/acme-bundle/assets/css dev/vendority/acme-bundle/assets/js/src/modules/hello dev/vendority/acme-bundle/assets/js/src/types.gitignore
Neue Datei
assets/node_modules assets/.npmrc assets/.__mf__temp
assets/.npmrc
Neue Datei
@hugeicons-pro:registry=https://npm.hugeicons.com/ //npm.hugeicons.com/:_authToken=${HUGEICONS_TOKEN} @vendority:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
assets/package.json
Neue Datei
{
"name": "vendority-acme-bundle",
"type": "module",
"private": true,
"version": "0.0.0",
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"verify:css": "node node_modules/@vendority/core/js/src/sdk/vite/verify-bundle-css.mjs"
},
"dependencies": {
"@hugeicons-pro/core-duotone-rounded": "^4.1.0",
"@hugeicons/react": "^1.1.6",
"@module-federation/enhanced": "^2.3.1",
"@module-federation/vite": "^1.15.1",
"@tailwindcss/vite": "^4.0.14",
"@types/lodash": "^4.17.16",
"@vendority/core": "^0.0.0-canary.20260913-135746-cd8c90f",
"lodash": "^4.18.1",
"react": "19.2.4",
"react-dom": "19.2.4",
"tailwindcss": "^4.0.14"
},
"devDependencies": {
"@babel/plugin-proposal-decorators": "^7.29.0",
"@babel/plugin-transform-class-properties": "^7.28.6",
"@types/react": "^19.0.10",
"@types/react-dom": "^19.0.4",
"@vitejs/plugin-react": "^4.7.0",
"i18next": "^24.2.3",
"react-i18next": "^15.4.1",
"typescript": "~5.7.2",
"vite": "^6.2.0",
"vite-plugin-symfony": "^8.0"
}
}assets/vite.config.ts
Neue Datei
import { createVendorityPluginConfig } from '@vendority/core/vite'
export default createVendorityPluginConfig({
name: 'acme',
alias: '@vendority/acme',
})assets/tsconfig.json
Neue Datei
{
"compilerOptions": {
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"isolatedModules": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"allowSyntheticDefaultImports": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"esModuleInterop": true,
"baseUrl": ".",
"paths": {
"@vendority/acme/api/*": ["build/api/*"],
"@vendority/acme/*": ["js/src/*"],
"@vendority/core": ["node_modules/@vendority/core/js/src/sdk/index.ts"],
"@vendority/core/api": ["node_modules/@vendority/core/js/src/sdk/api/index.ts"],
"@Vendority/*": ["node_modules/@vendority/core/js/src/core/*"],
"@VendorityApi/*": ["node_modules/@vendority/core/api/*"],
"@VendoritySDK/*": ["node_modules/@vendority/core/js/src/sdk/*"]
}
},
"include": ["js/src"]
}-
1
.gitignorehält die installierten Pakete und die.npmrcaus dem Repository heraus. -
2
.npmrcholt alle Pakete mit dem Präfix@vendorityvon GitHub Packages und die Symbole mit dem Präfix@hugeicons-provon Hugeicons. Die Tokens liest npm aus den UmgebungsvariablenGITHUB_PACKAGES_TOKENundHUGEICONS_TOKEN, sie stehen also nie in einer Datei. -
3
@vendority/coreenthält den Quellcode des Core-Frontends. Nehmen Sie die Canary-Version, die zu Ihrem installierten Core passt; die Bundles im Projekt zeigen, welche das ist. -
4
Die Symbole aus
@hugeicons-pro/core-duotone-roundedund@hugeicons/reactsowielodashimportieren die folgenden Tutorials direkt. Deshalb stehen sie als eigene Abhängigkeiten in derpackage.json. -
5
createVendorityPluginConfig()richtet Module Federation unter dem Namenvendority_acmeein, dazu Tailwind und das Zielpublic/buildim Bundle.namemuss mitgetPluginName()übereinstimmen. -
6
Die Pfade in
tsconfig.jsonleiten@vendority/coreund@Vendority/*auf den Quellcode im Paket um. Ohne sie findet TypeScript keine Typen für den Core und prüft dessen Importe nicht. -
7
npm run buildprüft zuerst die Typen mittsc -bund baut danach mit Vite.
Schritt 5 von 7
Den Einstiegspunkt des Plugins schreiben
Aus dem Build lädt der Core das Modul plugins.ts. Was diese Datei exportiert, meldet er als Plugin an.
assets/css/plugin.css
Neue Datei
@import "tailwindcss/theme" theme(reference) prefix(acme); @reference "../node_modules/@vendority/core/js/src/core/styles/theme.styles.css"; @import "tailwindcss/utilities" layer(utilities) prefix(acme); @source "../js/src/**/*.{ts,tsx}";
assets/js/src/main.ts
Neue Datei
// Platzhalter für Vite. Der Host lädt das Plugin über plugins.ts.
export {}assets/js/src/modules/hello/index.ts
Neue Datei
import type { AbstractModule } from '@vendority/core'
export const HelloModule: AbstractModule = {
onInit: () => {
console.log('Hello from the acme plugin!')
},
}assets/js/src/plugins.ts
Neue Datei
import '../../css/plugin.css'
import type { ModuleSystem, VendorityPlugin } from '@vendority/core'
import { HelloModule } from './modules/hello'
export const AcmePlugin: VendorityPlugin = {
name: 'acme',
priority: 100,
onStartup: ({ moduleSystem }: { moduleSystem: ModuleSystem }): void => {
moduleSystem.registerModule(HelloModule)
},
}assets/js/src/types/core-runtime-globals.d.ts
Neue Datei
export {}
declare global {
interface Window {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
Vendority: any
pluginRemotes?: Record<string, string>
}
}-
1
plugin.csserzeugt nur Tailwind-Klassen mit dem Präfixacme:, etwaacme:mt-4. Farben und Abstände liest Tailwind per@referenceaus dem Theme des Core, ohne sie ein zweites Mal auszugeben. -
2
main.tsbleibt leer. Vite braucht einen Einstiegspunkt, um überhaupt zu bauen; geladen wird die Datei nie. -
3
plugins.tsgibt Module Federation nach außen frei. Jedes exportierte Objekt mit einemnamemeldet der Core als Plugin an und ruft beim StartonStartupauf. -
4
onStartupbekommt das Modulsystem des Core als Argument. Darüber melden Sie Ihre Module an, hier das ModulHelloModule. -
5
Der Core ruft
onInitaller Module auf, nachdem jedes Plugin seine Module angemeldet hat. In diesen Methoden registrieren die folgenden Tutorials Seiten, Menüeinträge und Slots. -
6
core-runtime-globals.d.tsbeschreibtwindow.Vendorityundwindow.pluginRemotesfür TypeScript. Der Quellcode des Core greift auf beide zu, und ohne diese Datei schlägttsc -bfehl.
Schritt 6 von 7
Das Bundle im Projekt registrieren
Composer verlinkt das Bundle nach vendor, und ein Eintrag in config/bundles.php schaltet es ein.
Terminal
Befehl
docker compose exec -T php composer require 'vendority/acme-bundle:@dev'config/bundles.php
Geändert
<?php
return [
…
Vendority\Bundle\Core\VendorityCoreBundle::class => ['all' => true],
…
Vendority\Bundle\Acme\VendorityAcmeBundle::class => ['all' => true],
];+1 Zeile neu · grau: bestehender Code zur Orientierung
Terminal
Befehl
docker compose exec -T php php bin/console debug:container --tag=vendority.plugin-
1
composer requirefindet das Paket im Pfad-Repository, legtvendor/vendority/acme-bundleals Verweis auf Ihr Verzeichnis an und nimmt den Namensraum in den Autoloader auf. -
2
Ihr Bundle hat noch keine Versionsnummer, für Composer ist es deshalb eine Entwicklungsversion.
:@devlässt sie zu, auch wenn Ihre Installation sonst nur stabile Versionen annimmt. Ohne diesen Zusatz bricht der Befehl mit „Could not find a version of package vendority/acme-bundle matching your minimum-stability (stable)“ ab. -
3
In
config/bundles.phpträgt Composer das Bundle nicht ein. Diese Zeile ergänzen Sie selbst, am Ende der Liste. -
4
Der Kernel liest beim Start
config/bundles.phpund zusätzlichvar/plugins.php. Die zweite Datei schreibt der Plugin-Store für die Plugins, die er installiert; ein selbst entwickeltes Bundle gehört dort nicht hinein. -
5
debug:container --tag=vendority.pluginlistet alle Bundles, die der Core als Plugin kennt.
Schritt 7 von 7
Das Frontend bauen und das Ergebnis prüfen
Nach dem Build veröffentlicht assets:install die Dateien, und der Core bindet das Plugin beim nächsten Seitenaufruf ein.
Terminal
Befehl
cd dev/vendority/acme-bundle/assets
npm install
npm run build
cd ../../../..
docker compose exec -T php php bin/console assets:install --relative --symlink
curl -s http://app.vendority.local/ | grep -o '"acme":"[^"]*"'-
1
Setzen Sie vor
npm installdie UmgebungsvariablenGITHUB_PACKAGES_TOKENundHUGEICONS_TOKENauf Ihre beiden Tokens, sonst kann npm weder@vendority/corenoch die Symbole laden. Auch@vendority/coreselbst hängt von Hugeicons Pro ab; ohne den Eintrag für@hugeicons-proscheitertnpm installalso in jedem Fall. -
2
npm run buildschreibt das Frontend nachpublic/build/im Bundle. Darunter liegtremoteEntry.js, die Datei, die der Core lädt. -
3
assets:install --relative --symlinkverlinkt den Ordnerpublic/des Bundles nachpublic/bundles/vendorityacme/. Jeder weitere Build ist damit sofort sichtbar. Ohne--symlinkkopiert der Befehl die Dateien, und Sie müssen ihn nach jedem Build wiederholen. -
4
Jede Seite von Vendority listet die Plugins in
window.pluginRemotesauf. Der Eintragacmezeigt, dass der Core Ihr Plugin lädt. Die Zahl hinter?v=ist der Zeitpunkt des letzten Builds. -
5
Läuft Ihre Installation unter einer anderen Adresse, ersetzen Sie
app.vendority.localim letzten Befehl. -
6
Öffnen Sie Vendority im Browser. In der Konsole der Entwicklerwerkzeuge steht
Hello from the acme plugin!.
Geschafft.
Sie haben „Ein Bundle anlegen“ von Anfang bis Ende durchgearbeitet.
Blättern auch mit ← und →