Ein Bundle anlegen

7 Schritte·ca. 30 Min.·Einsteiger·Stand: September 2026

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/core zu installieren
  • Ein Token für die Paketquelle von Hugeicons Pro (npm.hugeicons.com), um die Symbole zu installieren
Schritt 1 von 7

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/translations
composer.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. 1

    Den Befehl führen Sie im Projektverzeichnis Ihrer Installation aus, wie alle Befehle in diesem Tutorial.

  2. 2

    Die composer.json des Projekts bindet über das Repository ./dev/*/* jedes Paket unter dev/ ein und verlinkt es nach vendor/. Änderungen am Code wirken deshalb sofort.

  3. 3

    Der Namensraum Vendority\Bundle\Acme\ zeigt auf src/. Er muss mit Vendority beginnen, denn nur bei solchen Bundles lädt der Core config/services.yaml, config/packages/ und config/routes/ automatisch.

  4. 4

    vendority/core steht 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. 1

    AbstractVendorityPluginBundle versieht das Bundle mit dem Tag vendority.plugin. Über diesen Tag findet der Core alle Plugins und bindet ihr Frontend ein.

  2. 2

    getPluginName() liefert den Kurznamen acme. Derselbe Name steht später in der Vite-Konfiguration und in pentatrion_vite.yaml.

  3. 3

    getViteBuildDirectory() nennt den öffentlichen Pfad des gebauten Frontends. Symfony veröffentlicht den Ordner public/ des Bundles unter public/bundles/vendorityacme/; der Name ergibt sich aus der Klasse VendorityAcmeBundle.

  4. 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. 5

    AbstractVendorityPluginExtension lädt services.yaml aus dem Ordner, den getConfigPath() 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: true
config/packages/pentatrion_vite.yaml Neue Datei
pentatrion_vite:
    configs:
        acme:
            build_directory: bundles/vendorityacme/build
Terminal 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. 1

    In services.yaml registrieren 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. 2

    autoconfigure: true sorgt dafür, dass Symfony registrierte Klassen, die eine Schnittstelle des Core implementieren, automatisch mit dem passenden Tag versieht.

  3. 3

    pentatrion_vite.yaml verbindet den Namen acme mit dem Build-Verzeichnis. Daran erkennt der Core auch, ob gerade ein Vite-Dev-Server für das Bundle läuft.

  4. 4

    Jede Datei unter config/packages/ lädt der Kernel automatisch, Routen unter config/routes/ ebenso. Die erste Route legen Sie im Tutorial „Einen API-Endpunkt anlegen“ an.

  5. 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. 1

    .gitignore hält die installierten Pakete und die .npmrc aus dem Repository heraus.

  2. 2

    .npmrc holt alle Pakete mit dem Präfix @vendority von GitHub Packages und die Symbole mit dem Präfix @hugeicons-pro von Hugeicons. Die Tokens liest npm aus den Umgebungsvariablen GITHUB_PACKAGES_TOKEN und HUGEICONS_TOKEN, sie stehen also nie in einer Datei.

  3. 3

    @vendority/core enthä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. 4

    Die Symbole aus @hugeicons-pro/core-duotone-rounded und @hugeicons/react sowie lodash importieren die folgenden Tutorials direkt. Deshalb stehen sie als eigene Abhängigkeiten in der package.json.

  5. 5

    createVendorityPluginConfig() richtet Module Federation unter dem Namen vendority_acme ein, dazu Tailwind und das Ziel public/build im Bundle. name muss mit getPluginName() übereinstimmen.

  6. 6

    Die Pfade in tsconfig.json leiten @vendority/core und @Vendority/* auf den Quellcode im Paket um. Ohne sie findet TypeScript keine Typen für den Core und prüft dessen Importe nicht.

  7. 7

    npm run build prüft zuerst die Typen mit tsc -b und 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. 1

    plugin.css erzeugt nur Tailwind-Klassen mit dem Präfix acme:, etwa acme:mt-4. Farben und Abstände liest Tailwind per @reference aus dem Theme des Core, ohne sie ein zweites Mal auszugeben.

  2. 2

    main.ts bleibt leer. Vite braucht einen Einstiegspunkt, um überhaupt zu bauen; geladen wird die Datei nie.

  3. 3

    plugins.ts gibt Module Federation nach außen frei. Jedes exportierte Objekt mit einem name meldet der Core als Plugin an und ruft beim Start onStartup auf.

  4. 4

    onStartup bekommt das Modulsystem des Core als Argument. Darüber melden Sie Ihre Module an, hier das Modul HelloModule.

  5. 5

    Der Core ruft onInit aller Module auf, nachdem jedes Plugin seine Module angemeldet hat. In diesen Methoden registrieren die folgenden Tutorials Seiten, Menüeinträge und Slots.

  6. 6

    core-runtime-globals.d.ts beschreibt window.Vendority und window.pluginRemotes für TypeScript. Der Quellcode des Core greift auf beide zu, und ohne diese Datei schlägt tsc -b fehl.

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. 1

    composer require findet das Paket im Pfad-Repository, legt vendor/vendority/acme-bundle als Verweis auf Ihr Verzeichnis an und nimmt den Namensraum in den Autoloader auf.

  2. 2

    Ihr Bundle hat noch keine Versionsnummer, für Composer ist es deshalb eine Entwicklungsversion. :@dev lä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. 3

    In config/bundles.php trägt Composer das Bundle nicht ein. Diese Zeile ergänzen Sie selbst, am Ende der Liste.

  4. 4

    Der Kernel liest beim Start config/bundles.php und zusätzlich var/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. 5

    debug:container --tag=vendority.plugin listet 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. 1

    Setzen Sie vor npm install die Umgebungsvariablen GITHUB_PACKAGES_TOKEN und HUGEICONS_TOKEN auf Ihre beiden Tokens, sonst kann npm weder @vendority/core noch die Symbole laden. Auch @vendority/core selbst hängt von Hugeicons Pro ab; ohne den Eintrag für @hugeicons-pro scheitert npm install also in jedem Fall.

  2. 2

    npm run build schreibt das Frontend nach public/build/ im Bundle. Darunter liegt remoteEntry.js, die Datei, die der Core lädt.

  3. 3

    assets:install --relative --symlink verlinkt den Ordner public/ des Bundles nach public/bundles/vendorityacme/. Jeder weitere Build ist damit sofort sichtbar. Ohne --symlink kopiert der Befehl die Dateien, und Sie müssen ihn nach jedem Build wiederholen.

  4. 4

    Jede Seite von Vendority listet die Plugins in window.pluginRemotes auf. Der Eintrag acme zeigt, dass der Core Ihr Plugin lädt. Die Zahl hinter ?v= ist der Zeitpunkt des letzten Builds.

  5. 5

    Läuft Ihre Installation unter einer anderen Adresse, ersetzen Sie app.vendority.local im letzten Befehl.

  6. 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.

Zurück zu „Grundlagen“

Blättern auch mit ← und →