Sulu Headless Bundle: API-First Content Management mit Symfony

„Wir brauchen eine moderne React-Applikation, aber das CMS muss trotzdem nutzbar bleiben“ – ein Satz, den ihr als Symfony-Developer oder technische Entscheider bestimmt schon gehört habt. Mit dem Sulu Headless Bundle bekommt ihr genau diese Flexibilität: Content-Management mit der vollen Sulu-Power, gepaart mit einer sauberen JSON-API für euer Frontend. Nach über 15 Jahren Erfahrung in Softwarequalität, Open Source und Remote Consulting zeigen wir euch, wie ihr das Bundle optimal einsetzt und welche Fallstricke ihr vermeiden solltet.

Warum Headless CMS im Enterprise-Umfeld immer wichtiger wird

Die Anforderungen an moderne Web-Projekte haben sich drastisch verändert. Content muss heute nicht nur auf klassischen Websites ausgespielt werden, sondern auch auf Mobile Apps, Digital Signage, IoT-Devices und in Custom-Applikationen. Ein decoupled CMS wie Sulu mit dem Headless Bundle gibt euch diese Flexibilität, ohne dass ihr auf die Vorteile einer vollständigen Content-Management-Lösung verzichten müsst.

Das Team von Never Code Alone hat in zahlreichen Enterprise-Projekten erlebt, wie der hybride Ansatz von Sulu – traditionelles Rendering plus API-Zugang – die Entwicklungszeit verkürzt und gleichzeitig maximale Flexibilität bietet.

1. Was ist das Sulu Headless Bundle und welche Vorteile bietet es?

Das SuluHeadlessBundle erweitert das Sulu CMS um Controller und Services, die euch ermöglichen, Page-Content als reines JSON auszuliefern. Statt fertiger HTML-Seiten bekommt euer Frontend strukturierte Daten, die es selbst rendern kann.

Die wichtigsten Features im Überblick:

• JSON-API für alle Page-Templates
• REST-Endpoints für Navigation und Snippet Areas
• Optionales React/MobX SPA-Setup als Referenz-Implementierung
• Vollständige Kompatibilität mit Sulu ab Version 2.0
• Frontend-agnostisch: Nutzt React, Vue, Angular oder jedes andere Framework

Pro-Tipp aus der Praxis: Das Bundle ist ideal für Projekte, bei denen Backend-Teams mit Symfony arbeiten und Frontend-Teams moderne JavaScript-Frameworks bevorzugen – die klare API-Trennung macht parallele Entwicklung möglich.

2. Wie installiere ich das Sulu Headless Bundle korrekt?

Die Installation erfolgt über Composer in wenigen Schritten:

composer require sulu/headless-bundle

Aktiviert das Bundle in eurer config/bundles.php:

return [
    // andere Bundles...
    SuluBundleHeadlessBundleSuluHeadlessBundle::class => ['all' => true],
];

Bindet die Routes in config/routes/sulu_headless_website.yml ein:

sulu_headless:
    type: portal
    resource: "@SuluHeadlessBundle/Resources/config/routing_website.yml"

Consulting-Tipp: Testet die Installation zuerst in einer lokalen Docker-Umgebung, bevor ihr sie auf Staging deployt. Das Bundle befindet sich noch in aktiver Entwicklung und deckt noch nicht alle Use Cases ab.

3. Welche Symfony- und PHP-Versionen werden unterstützt?

Das Bundle unterstützt eine breite Range an Versionen für maximale Flexibilität:

• PHP: 7.3 oder höher, inklusive PHP 8.0, 8.1, 8.2 und 8.3
• Sulu: Ab Version 2.4, inklusive 2.5 und 2.6
• Symfony: 4.4, 5.4, 6.3 und 7.0

Die aktuelle stabile Version ist 0.10.5 (Stand April 2025). Beachtet, dass das Bundle als Pre-Release markiert ist – für Production-Einsätze empfehlen wir zusätzliche Absicherung durch Tests und Caching-Strategien.

4. Wie konfiguriere ich Templates für die JSON-Ausgabe?

Um ein Template für die Headless-Ausgabe zu aktivieren, müsst ihr den Controller in eurer Template-XML anpassen:

<?xml version="1.0" ?>
<template xmlns="http://schemas.sulu.io/template/template"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/template/template">

    <key>default</key>
    <controller>SuluBundleHeadlessBundleControllerHeadlessWebsiteController::indexAction</controller>
    <!-- Template-Konfiguration -->
</template>

Bei Requests mit .json-Suffix liefert der Controller automatisch JSON statt HTML. Bei normalen Requests steht die JSON-Struktur trotzdem als headless-Variable im Twig-Template zur Verfügung – perfekt für Server-Side Rendering mit anschließender Client-Side Hydration.

5. Welche Frontend-Frameworks funktionieren mit dem Headless Bundle?

Das SuluHeadlessBundle ist bewusst frontend-agnostisch designt. Ihr könnt jedes Framework nutzen:

✅ React – inkl. Next.js für SSR
✅ Vue.js – mit Nuxt.js für Universal-Apps
✅ Angular – für Enterprise-SPAs
✅ Remix – Sulu.io selbst nutzt Remix im Headless-Modus
✅ Svelte/SvelteKit – für performante Anwendungen

Das Bundle enthält eine optionale Referenz-Implementierung mit React und MobX im Verzeichnis Resources/js-website. Diese könnt ihr als Startpunkt für eigene Projekte nutzen:

cd assets/headless
npm install
npm run build

Entscheider-Perspektive: Die Framework-Freiheit bedeutet, dass ihr Frontend-Talente einstellen könnt, die sich mit modernen JS-Tools auskennen – ohne Sulu-spezifisches Know-how vorauszusetzen.

6. Wie nutze ich die Navigation-API im Headless-Modus?

Das Bundle stellt dedizierte REST-Endpoints für Navigation bereit. Die URLs sind Portal-spezifisch:

/api/navigations/{context}?depth=2&flat=false&excerpt=true

Parameter im Detail:

• depth – Maximale Tiefe des Navigationsbaums
• flat – Als flache Liste statt Baum ausgeben
• excerpt – Excerpt-Daten einbinden

Beispiel-Response:

{
  "items": [
    {
      "title": "Home",
      "url": "/",
      "children": []
    },
    {
      "title": "Produkte",
      "url": "/produkte",
      "children": [...]
    }
  ]
}

Für Snippet Areas existiert ein analoger Endpoint:

/api/snippet-areas/{key}?includeExtension=true

7. Brauche ich eigene ContentTypeResolver für Custom Content Types?

Sulu verwendet intern ContentType-Services, die teilweise nicht-skalare Werte wie Media-Entities zurückgeben. Da JSON nur skalare Werte unterstützt, führt das Headless Bundle ContentTypeResolver-Services ein.

Für Standard-Content-Types wie media_selection, block, page_selection sind bereits Resolver enthalten. Bei eigenen Content Types implementiert ihr das ContentTypeResolverInterface:

<?php

namespace AppContentTypeResolver;

use SuluBundleHeadlessBundleContentContentTypeResolverContentTypeResolverInterface;
use SuluBundleHeadlessBundleContentContentView;
use SuluComponentContentCompatPropertyInterface;

class CustomTypeResolver implements ContentTypeResolverInterface
{
    public static function getContentType(): string
    {
        return 'my_custom_type';
    }

    public function resolve(
        $data, 
        PropertyInterface $property, 
        string $locale, 
        array $attributes = []
    ): ContentView {
        return new ContentView(
            ['processed' => $data],
            ['raw' => $data]
        );
    }
}

Registriert den Service mit dem Tag sulu_headless.content_type_resolver in eurer services.yaml.

8. Wie optimiere ich die Performance bei Headless-Setups?

Headless bedeutet nicht automatisch bessere Performance – im Gegenteil: Ohne durchdachtes Caching kann die Architektur zum Bottleneck werden. Folgende Strategien haben sich bewährt:

Varnish-Integration:

# config/packages/sulu_http_cache.yaml
sulu_http_cache:
    tags:
        enabled: true
    cache:
        max_age: 240
        shared_max_age: 480
    proxy_client:
        varnish:
            enabled: true
            servers: ['127.0.0.1:80']

CDN für API-Responses: Nutzt Fastly, Cloudfront oder ähnliche Services vor eurer Node.js-Applikation.

SSR-Caching: Bei React/Next.js oder Remix sollten gerenderte Seiten gecached werden – ohne Caching muss Node.js bei jedem Request rendern.

Consulting-Erfahrung: In einem Enterprise-Projekt konnten wir die Response-Zeiten von 800ms auf unter 50ms reduzieren, indem wir Varnish vor das API-Backend und Cloudflare vor die Node.js-Applikation geschaltet haben.

9. Welche Vorteile bietet der hybride Ansatz gegenüber reinen Headless-CMS?

Sulu verfolgt bewusst den decoupled-Ansatz statt pure Headless. Die Vorteile:

Aspekt	Reines Headless CMS	Sulu Hybrid
Preview im Admin	Meist nicht möglich	✅ Volle Preview-Funktion
Caching	Selbst implementieren	✅ Integriert mit Invalidierung
Bildverarbeitung	Externe Services	✅ Integrierte Resize-Pipeline
Redakteurs-Experience	Oft eingeschränkt	✅ Vollständiges CMS
Fallback zu SSR	Aufwändig	✅ Twig-Templates nutzbar

Das Team von Sulu hat die eigene Website sulu.io im Headless-Modus mit Remix neu gebaut und dabei wichtige Erkenntnisse gewonnen: Headless bringt Komplexität bei Deployments, Caching und Debugging. Der hybride Ansatz gibt euch die Freiheit, projektspezifisch zu entscheiden.

10. Wie starte ich ein React/Next.js-Projekt mit Sulu Headless?

Ein typisches Setup kombiniert Sulu als Backend mit einem separaten Frontend-Projekt:

Backend-Struktur (Sulu):

/config
/src
/templates
/public
composer.json

Frontend-Struktur (Next.js/Remix):

/components
/pages (oder /app bei App Router)
/lib/api.ts
package.json

In eurem Frontend fetcht ihr die Sulu-API:

// lib/api.ts
export async function getPage(path: string) {
  const response = await fetch(
    `${process.env.SULU_API_URL}${path}.json`
  );
  return response.json();
}

Wichtig für Production: Stellt sicher, dass ein Caching-Layer (Varnish, Cloudflare) zwischen eurer Node-Applikation und Sulu steht. Ohne Cache muss jeder Request durch beide Systeme – das skaliert nicht.

Best Practices aus unserer Consulting-Erfahrung

Nach zahlreichen Headless-Projekten haben wir bei Never Code Alone folgende Standards etabliert:

✅ Staging-Environment: Immer mit identischer Caching-Konfiguration wie Production
✅ API-Versionierung: Plant von Anfang an Versionierung ein
✅ Error Handling: Fallback-Strategien für API-Ausfälle im Frontend
✅ Content-Preview: Nutzt Sulud Preview-Features auch im Headless-Modus
✅ Monitoring: APM-Tools für beide Systeme (Backend + Frontend)

Fazit: Wann lohnt sich das Sulu Headless Bundle?

Das Sulu Headless Bundle ist die richtige Wahl, wenn ihr:

• Moderne JavaScript-Frontends mit einem bewährten PHP-CMS verbinden wollt
• Symfony-Expertise im Team habt und diese nutzen möchtet
• Die Flexibilität braucht, Content auf mehreren Kanälen auszuspielen
• Einen hybriden Ansatz bevorzugt, der euch Optionen offen hält

Für reine Content-Websites ohne spezielle Frontend-Anforderungen ist klassisches Sulu mit Twig-Templates oft die effizientere Lösung. Die Entscheidung sollte projektspezifisch getroffen werden.

Direkte Unterstützung für euer Projekt

Ihr plant ein Headless-Projekt mit Sulu oder habt Fragen zur optimalen Architektur? Mit über 15 Jahren Expertise in Softwarequalität, Open Source und Remote Consulting unterstützen wir euch gerne – von der Konzeption bis zum Production-Deployment.

Kontakt: roland@nevercodealone.de

Gemeinsam entwickeln wir die Architektur, die zu eurem Team und euren Anforderungen passt – keine theoretischen Konzepte, sondern praktische Lösungen die funktionieren.

Never Code Alone – Gemeinsam für bessere Software-Qualität!