Zum Hauptinhalt springen

ADR - Frontend Runtime Config Format

Status​

accepted

Kontext​

Aktuell werden umgebungsspezifische Frontend-Werte teilweise ueber Angular fileReplacements und environment.*.ts ausgerollt (z. B. Preview-spezifische API-URLs).
Das ist fuer kurzfristige Stabilisierung nutzbar, aber kein langfristig belastbares Modell fuer containerisierte, wegwerfbare Preview-Umgebungen.

Zielbild:

  • Ein Docker Image pro Commit
  • Umgebungsspezifische Werte zur Laufzeit
  • Keine API-/Remote-/Keycloak-URLs ueber Build-time File-Replacements

Optionen​

Option A - assets/runtime-config.json​

Beispiel:

{
  "auth": {
    "url": "https://account.taskly24.de",
    "realm": "guides",
    "clientId": "taskly-preview"
  },
  "apis": {
    "todos": "https://preview-todos-api.taskly24.de"
  },
  "remotes": {
    "todos": "https://preview-todos.taskly24.de/mf-manifest.json"
  },
  "preview": {
    "enabled": true,
    "name": "preview"
  }
}

Vorteile:

  • klares Datenformat
  • gut testbar (curl, jq)
  • gut fuer Angular und React konsumierbar
  • sauberer Vertrag zwischen Deployment und App

Nachteile:

  • muss vor Bootstrap geladen werden
  • erfordert asynchrone Initialisierung

Option B - assets/env.js​

Beispiel:

window.__TASKLY_RUNTIME_CONFIG__ = {
  auth: {
    url: 'https://account.taskly24.de',
    realm: 'guides',
    clientId: 'taskly-preview',
  },
};

Vorteile:

  • sofort im Browser verfuegbar
  • kein zusaetzlicher JSON-Fetch notwendig

Nachteile:

  • globaler Window-State
  • schwaechere Typisierung und Vertragsklarheit

Entscheidung​

Wir nutzen Option A (assets/runtime-config.json) als verbindliches Zielbild.

Verbindlicher Kontrakt​

Mindestens folgende Felder sind runtime-konfigurierbar:

  • auth.url
  • auth.realm
  • auth.clientId
  • remotes.<remoteName>
  • apis.<domainName>

Fuer Preview zusaetzlich:

  • preview.enabled
  • preview.name

Abgrenzung zu environment.ts​

environment.ts bleibt fuer Build-Flags und lokale Dev-Aspekte, z. B.:

  • production
  • Debug/Tracing-Schalter
  • lokale technische Defaults ohne Deploy-Relevanz

Nicht mehr in environment.*.ts:

  • API-URLs
  • Remote-Manifest-URLs
  • Keycloak URL/Realm/ClientId
  • andere deploy-spezifische Endpunkte

Konsequenzen​

Positiv:

  • einheitliches Laufzeitmodell fuer Preview und weitere Umgebungen
  • weniger Bundle-Varianten
  • bessere Nachvollziehbarkeit und Diagnose im Betrieb

Negativ:

  • Initiale Umstellung in Host/Remotes notwendig (Bootstrap mit Runtime-Config)
  • bestehende Preview-FileReplacement-Pfade muessen schrittweise rueckgebaut werden

Migration (Leitplanken)​

  1. Runtime-Config zuerst fuer Host + ein Remote produktiv nachweisen.
  2. Danach Preview-FileReplacements schrittweise entfernen.
  3. Keine neuen Preview-spezifischen environment.preview.ts mehr einfuehren.
  4. Production-Deploymentverhalten darf waehrend der Migration nicht regressieren.