White-Label-Theming ohne Rebuild: Laufzeit-CSS-Variablen pro Mandant

1. Das Skalierungsproblem von Build-Time-Multi-Brand

Der klassische Ansatz für White-Label-Theming generiert für jede Marke einen eigenen Tailwind-Build mit eigener Konfigurationsdatei, eigenem @theme-Block und eigenem kompiliertem CSS-Bundle. Für fünf oder zehn Marken funktioniert das gut, weil sich der zusätzliche Build-Aufwand noch überschaubar in der CI-Pipeline unterbringen lässt. Sobald ein SaaS-Produkt aber hundert oder tausend Mandanten mit individuellem Farbschema bedienen soll, wird dieser Ansatz zum Flaschenhals.

Jede neue Marke bedeutet einen neuen Build-Job, eine neue Deployment-Pipeline-Ausführung und ein zusätzliches CSS-Bundle, das separat gehostet und ausgeliefert werden muss. Ändert ein Mandant nur eine einzige Akzentfarbe, läuft der komplette Build-Prozess erneut durch, inklusive Tailwind-Kompilierung, Minifizierung und Cache-Invalidierung. Für ein Produkt mit häufigen, kleinen Branding-Änderungen ist das White-Label-Theming über separate Builds unnötig langsam und ressourcenintensiv.

Der Ausweg liegt nicht in noch schnelleren Build-Pipelines, sondern in einer grundlegend anderen Architektur: einem einzigen kompilierten CSS-Bundle für alle Mandanten, das seine tatsächlichen Farbwerte erst zur Laufzeit über CSS Custom Properties erhält. White-Label-Theming wird dadurch von einem Build-Time-Problem zu einem reinen Datenproblem, das sich pro Anfrage lösen lässt.

2. Die Single-Bundle-Strategie

Der Kerngedanke hinter Laufzeit-basiertem White-Label-Theming ist simpel: Tailwind CSS v4 kompiliert genau einmal, mit Standardwerten für alle theme-abhängigen Design-Tokens im @theme-Block. Diese Standardwerte fungieren als sichtbarer Fallback, falls für einen Mandanten aus irgendeinem Grund keine spezifische Konfiguration vorliegt, etwa bei einem neuen Kunden während der Onboarding-Phase.

Für den tatsächlichen Marken-Look überschreibt eine kleine, dynamisch generierte CSS-Regel die relevanten Custom Properties direkt im :root-Selektor, ausgeliefert als Inline-<style>-Block im HTML-Head. Dieser Block wird bei jeder Anfrage serverseitig aus der Mandanten-Konfiguration in der Datenbank erzeugt, während das eigentliche, große Tailwind-CSS-Bundle unverändert aus dem Cache oder CDN kommt.

Der entscheidende Vorteil dieser Aufteilung: Das große, statische Bundle profitiert von aggressivem Browser- und CDN-Caching über sehr lange Zeiträume, weil es sich nie ändert, während der kleine, mandantenspezifische Overlay-Block nur wenige hundert Bytes umfasst und trotzdem bei jeder Anfrage frisch generiert werden kann, ohne spürbare Latenz zu verursachen.

/* Base Tailwind v4 tokens, compiled once for all tenants */
@theme {
  --color-brand-primary: #0ea5e9;
  --color-brand-secondary: #0c4a6e;
  --color-brand-surface: #ffffff;
  --font-brand-heading: "Inter", sans-serif;
}

/* Components consume the tokens indirectly, never a hardcoded hex value */
.btn-primary {
  background-color: var(--color-brand-primary);
  font-family: var(--font-brand-heading);
}

3. Mandanten-Erkennung anhand des Hostnamens

Damit der Server weiß, welche Marke für eine eingehende Anfrage gilt, braucht White-Label-Theming eine zuverlässige Mandanten-Erkennung. Der gängigste Ansatz nutzt den Host-Header der HTTP-Anfrage, entweder über eine dedizierte Subdomain je Mandant, etwa kunde-a.produkt.de, oder über eine vollständig eigene Domain, die der Kunde selbst mitbringt und per CNAME auf die Plattform zeigt.

Der Hostname wird gegen eine Mandanten-Tabelle in der Datenbank abgeglichen, die neben der Mandanten-ID auch die Branding-Konfiguration als JSON-Struktur mit Farbwerten, Logo-URL und Schriftart enthält. Dieser Lookup sollte konsequent gecacht werden, etwa in Redis mit kurzer Time-to-Live, weil er sonst bei jeder einzelnen Anfrage eine zusätzliche Datenbankabfrage auslöst, die sich über viele gleichzeitige Nutzer summiert.

Für White-Label-Theming in einem Magento- oder Hyvä-Kontext lässt sich derselbe Mechanismus über einen Website- oder Store-View-Code abbilden, der bereits Teil der bestehenden Multi-Site-Architektur ist. Der Vorteil: Die Mandanten-Erkennung muss nicht neu erfunden werden, sondern nutzt eine Struktur, die für Multi-Site-Betrieb ohnehin schon vorhanden ist.

<?php
declare(strict_types=1);

namespace Mironsoft\WhiteLabel\Service;

/**
 * Resolves tenant branding config based on the request hostname.
 */
final class TenantThemeResolver
{
    public function __construct(
        private readonly TenantConfigCache $cache,
        private readonly TenantRepositoryInterface $tenantRepository,
    ) {
    }

    /**
     * Looks up the tenant branding tokens for a given hostname.
     *
     * @param string $host
     * @return array{primary: string, secondary: string, surface: string, font: string}
     */
    public function resolve(string $host): array
    {
        $cached = $this->cache->get($host);
        if ($cached !== null) {
            return $cached;
        }

        $tenant = $this->tenantRepository->findByHost($host);
        $tokens = $tenant?->getBrandingTokens() ?? $this->defaultTokens();

        $this->cache->set($host, $tokens, 300);

        return $tokens;
    }

    /**
     * Fallback tokens matching the base @theme block.
     *
     * @return array{primary: string, secondary: string, surface: string, font: string}
     */
    private function defaultTokens(): array
    {
        return [
            'primary' => '#0ea5e9',
            'secondary' => '#0c4a6e',
            'surface' => '#ffffff',
            'font' => 'Inter',
        ];
    }
}

4. CSS-Variablen zur Laufzeit injizieren

Mit den aufgelösten Mandanten-Token generiert die Anwendung einen kompakten Inline-<style>-Block, der ausschließlich die Custom Properties überschreibt, die sich vom Standard-@theme-Block unterscheiden. Dieser Block wird direkt im <head> vor dem großen Tailwind-Bundle platziert, sodass die Kaskade die überschriebenen Werte automatisch bevorzugt, ohne dass zusätzliche Selektor-Spezifität nötig wäre.

Wichtig für konsistentes White-Label-Theming: Der generierte Block enthält ausschließlich Custom-Property-Deklarationen, keine vollständigen Komponentenregeln. Das hält den Overlay minimal, meist unter einem Kilobyte, und stellt sicher, dass jede Änderung an der Komponentenstruktur weiterhin zentral im großen Tailwind-Bundle gepflegt wird, statt sich über verstreute Mandanten-Overrides zu duplizieren.

Der HTML-Output selbst bleibt dabei serverseitig gerendert und cachebar, solange der Cache-Schlüssel den Hostnamen mit einschließt. Für Frameworks mit clientseitigem Rendering lässt sich derselbe Mechanismus über einen frühen Fetch der Mandanten-Konfiguration und ein serverseitig vorgerendertes Style-Tag im initialen HTML umsetzen, um ein kurzes Aufblitzen falscher Farben beim ersten Laden zu vermeiden.

<head>
  <!-- Generated per request based on the resolved tenant -->
  <style id="tenant-theme-overrides">
    :root {
      --color-brand-primary: #16a34a;
      --color-brand-secondary: #14532d;
      --color-brand-surface: #f0fdf4;
      --font-brand-heading: "Poppins", sans-serif;
    }
  </style>

  <!-- Large, static Tailwind bundle, identical for every tenant -->
  <link rel="stylesheet" href="/assets/app.css">
</head>

5. Sicherheit: CSS-Injection zuverlässig vermeiden

Sobald Nutzerdaten, auch wenn sie nur von Kunden-Administratoren stammen, direkt in ein <style>-Tag eingebettet werden, entsteht ein potenzielles CSS-Injection-Risiko. Ein bösartig eingegebener Wert wie #000; } body { display: none; } /* könnte theoretisch aus dem eigentlichen Farbwert ausbrechen und beliebiges CSS einschleusen. White-Label-Theming ohne strikte Validierung der Eingabewerte ist deshalb ein Sicherheitsrisiko, kein rein kosmetisches Feature.

Der zuverlässigste Schutz ist eine strikte Whitelist des erlaubten Wertformats: Nur gültige Hex-Farbcodes, RGB-Funktionsnotationen oder eine begrenzte Liste erlaubter Schriftartnamen dürfen überhaupt in die Konfiguration gelangen, geprüft über einen regulären Ausdruck sowohl beim Speichern in der Admin-Oberfläche als auch erneut beim Ausgeben des Style-Blocks. Jeder Wert, der dieses Muster nicht erfüllt, wird verworfen und durch den Fallback-Wert aus dem Basis-@theme-Block ersetzt.

Eine zusätzliche Absicherung ist eine Content-Security-Policy mit einem Nonce für den Inline-Style-Block, sofern das Projekt ohnehin schon CSP für Skripte einsetzt, wie es bei Hyvä mit dem CSP-Modul üblich ist. So bleibt White-Label-Theming auch dann sicher, wenn eine einzelne Validierungsebene versagen sollte.

6. @theme als Fallback-Grundgerüst

Der Basis-@theme-Block bleibt bei diesem Ansatz mehr als nur ein Startwert, er ist die einzige Quelle der Wahrheit für die Struktur der Design-Tokens. Jeder Mandant kann nur Werte überschreiben, die im Basis-Block bereits als Custom Property existieren, niemals neue, unbekannte Variablennamen einführen. Das hält White-Label-Theming vorhersagbar, weil Entwickler beim Schreiben von Komponenten immer gegen dieselbe, feste Menge an Tokens arbeiten.

Für Mandanten ohne eigene Konfiguration, etwa während eines Testzugangs oder direkt nach der Registrierung, greifen automatisch die Standardwerte aus dem Basis-Block. Das verhindert eine kaputte Optik für neue Kunden, die noch keine eigenen Farben hinterlegt haben, und macht das Onboarding unabhängig von einer sofort vollständigen Branding-Konfiguration.

In der Praxis bewährt sich eine klare Trennung zwischen Tokens, die White-Label-fähig sind, etwa Primär- und Sekundärfarbe, Oberflächenfarbe und Schriftart, und Tokens, die für alle Mandanten identisch bleiben, etwa Abstände, Radien oder Schriftgrößen. Nur die White-Label-fähigen Tokens durchlaufen den Runtime-Injection-Mechanismus, alle anderen bleiben fest im kompilierten Bundle verankert.

7. Caching-Strategie pro Mandant

Effizientes Caching ist der Schlüssel dafür, dass White-Label-Theming mit Laufzeit-Injection nicht zu einem Performance-Nachteil gegenüber Build-Time-Ansätzen wird. Das große, statische Tailwind-Bundle erhält einen Cache-Control-Header mit sehr langer Gültigkeitsdauer und einem Hash im Dateinamen, damit neue Deployments automatisch eine neue URL erzeugen und alte Caches nicht ungültig gemacht werden müssen.

Der HTML-Response mit dem eingebetteten Mandanten-Style-Block braucht dagegen einen differenzierteren Cache-Ansatz. Ein CDN-Cache-Schlüssel, der den Hostnamen mit einschließt, sorgt dafür, dass jeder Mandant seine eigene, korrekt eingefärbte Version der Seite aus dem Cache erhält, während die Datenbankabfrage für die Mandanten-Konfiguration selbst mit einer kurzen Time-to-Live in Redis oder einem vergleichbaren In-Memory-Store zwischengespeichert wird.

Ändert ein Mandant seine Markenfarbe über die Admin-Oberfläche, muss ausschließlich der Cache-Eintrag dieses einen Hostnamens invalidiert werden, niemals das gesamte CSS-Bundle oder die Caches anderer Mandanten. Das ist ein struktureller Vorteil gegenüber Build-Time-Ansätzen, bei denen eine Änderung immer einen kompletten neuen Build-Zyklus auslöst.

# Static bundle: long-lived, immutable, hash in filename
curl -I https://cdn.produkt.de/assets/app.a1b2c3d4.css
# Cache-Control: public, max-age=31536000, immutable

# HTML response: cached per tenant hostname via CDN cache key
curl -I -H "Host: kunde-a.produkt.de" https://produkt.de/
# Cache-Control: private, max-age=60
# Vary: Host

8. Admin-Oberfläche mit Live-Vorschau

Für Kunden, die ihr eigenes White-Label-Theming selbst konfigurieren sollen, ohne Entwickler-Support anzufragen, lohnt sich eine kleine Admin-Oberfläche mit Farbwählern und einer Live-Vorschau. Alpine.js eignet sich hierfür gut, weil sich die gewählten Farbwerte direkt in x-bind:style an CSS Custom Properties eines Vorschau-Containers binden lassen, ohne dass ein vollständiger Seiten-Reload nötig wäre.

Die Live-Vorschau simuliert exakt denselben Mechanismus, der später serverseitig für den echten Seitenaufruf greift: Custom Properties werden im :root-Kontext des Vorschau-Containers gesetzt, während dieselben Tailwind-Komponentenklassen wie in der echten Anwendung verwendet werden. So sieht der Kunde vor dem Speichern exakt das Ergebnis, das später live auf seiner Subdomain erscheint, ohne Diskrepanz zwischen Vorschau und Produktion.

Beim Speichern durchläuft jeder eingegebene Wert dieselbe Validierung wie in Abschnitt fünf beschrieben, bevor er in der Mandanten-Konfiguration landet. Erst nach erfolgreicher Validierung wird der zugehörige Cache-Eintrag invalidiert, damit fehlerhafte Eingaben niemals live auf der Seite des Mandanten erscheinen.

// Alpine.js component for the tenant branding admin preview
function tenantThemeEditor() {
  return {
    primary: '#0ea5e9',
    secondary: '#0c4a6e',

    get previewStyle() {
      return `--color-brand-primary: ${this.primary}; ` +
             `--color-brand-secondary: ${this.secondary};`;
    },

    async save() {
      const response = await fetch('/admin/tenant/theme', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          primary: this.primary,
          secondary: this.secondary,
        }),
      });

      if (!response.ok) {
        alert('Validation failed, colors were not saved.');
      }
    },
  };
}

9. Build-Time versus Runtime-Injection im Vergleich

Beide Ansätze lösen dasselbe Grundproblem, unterscheiden sich aber deutlich in Skalierbarkeit, Änderungsgeschwindigkeit und operativem Aufwand. Die folgende Tabelle stellt beide Strategien für White-Label-Theming direkt gegenüber.

Der Vergleich zeigt, dass White-Label-Theming per Runtime-Injection vor allem dann seine Stärken ausspielt, wenn die Zahl der Mandanten groß ist oder Kunden ihre Farben selbst verwalten sollen. Für sehr kleine Multi-Brand-Projekte mit wenigen, selten wechselnden Marken kann ein klassischer Build-Time-Ansatz wegen des geringeren Sicherheitsaufwands weiterhin die einfachere Wahl sein.

10. Zusammenfassung

White-Label-Theming ohne Rebuild pro Marke basiert auf einer klaren Trennung zwischen einem einzigen, unveränderlichen Tailwind-Bundle und einem kleinen, mandantenspezifischen CSS-Variablen-Overlay, der serverseitig anhand des Hostnamens generiert wird. Die Mandanten-Erkennung nutzt den Host-Header, die eigentliche Farblogik bleibt im Basis-@theme-Block verankert, und nur die tatsächlich White-Label-fähigen Tokens durchlaufen den Runtime-Injection-Mechanismus.

Sicherheit ist bei diesem Ansatz kein Nebenaspekt: Jeder eingegebene Farbwert muss strikt gegen ein erlaubtes Format validiert werden, bevor er in ein Inline-Style-Tag gelangt. In Kombination mit einer sauberen Caching-Strategie pro Hostname skaliert White-Label-Theming auf diese Weise auf hunderte oder tausende Mandanten, ohne dass sich Build-Zeit oder Hosting-Aufwand mit jeder neuen Marke vervielfachen.

11. FAQ: White-Label-Theming ohne Rebuild pro Marke