Lokale Entwicklung mit Zoho Catalyst und Nuxt: So habe ich es gelöst

Wer Zoho Catalyst als Backend für eine moderne Webanwendung einsetzt, steht schnell vor einer Herausforderung: Wie entwickle ich lokal, wenn Catalyst OAuth, SDK-Initialisierung und serverlose Funktionen über eigene Endpunkte bereitstellt? In diesem Beitrag zeige ich, wie ich die lokale Entwicklung meiner Nuxt-App mit Zoho Catalyst produktiv und stabil eingerichtet habe.

Das Problem: Zwei Server, ein Browser

Im Produktivbetrieb läuft alles über Catalyst: Die Nuxt-App wird als statische SPA deployed, Catalyst kümmert sich um Authentifizierung, SDK-Initialisierung und die Ausführung von Serverless Functions. Lokal sieht die Welt anders aus:

• Nuxt Dev Server läuft auf localhost:3000 und liefert die App mit Hot Module Replacement.
• Catalyst CLI (catalyst serve) läuft auf localhost:3838 und stellt OAuth, das SDK und die lokale Authentifizierung bereit.

Das Problem: Der Browser spricht nur mit localhost:3000. Anfragen an Catalyst-Endpunkte wie /__catalyst/sdk/init.js oder /oauthorize laufen ins Leere, weil Nuxt davon nichts weiß.

Die Lösung: Vite Proxy als Brücke

Nuxt nutzt unter der Haube Vite als Dev Server. Vite bringt eine eingebaute Proxy-Funktion mit, die Anfragen transparent an andere Server weiterleiten kann. Genau das habe ich mir zunutze gemacht.

In meiner nuxt.config.ts leite ich alle relevanten Catalyst-Routen per Vite Proxy an die richtige Stelle weiter:

vite: {
  server: {
    proxy: {
      "/__catalyst": {
        target: "http://localhost:3838",
        changeOrigin: true,
      },
      "/accounts": {
        target: "http://localhost:3838",
        changeOrigin: true,
      },
      "/oauthorize": {
        target: "http://localhost:3838",
        changeOrigin: true,
      },
      "/server": {
        target: "https://meine-app.development.catalystserverless.eu",
        changeOrigin: true,
        secure: true,
      },
    },
  },
},

Was passiert hier genau?

• /__catalyst – Das Catalyst SDK wird über diesen Pfad initialisiert. Ohne Proxy würde das Script im Browser nicht geladen werden.
• /accounts und /oauthorize – Diese Routen werden für den OAuth-Login-Flow benötigt. Catalyst leitet Nutzer:innen hierüber zur Anmeldung und zurück.
• /server – Aufrufe an meine Serverless Functions. Hier zeige ich den Proxy nicht auf den lokalen Catalyst-Server, sondern auf die deployed Version in der Cloud. Das hat einen guten Grund: Die Functions laufen so immer stabil gegen die aktuelle Serverversion, unabhängig davon, ob ich lokal gerade an der Function-Logik arbeite oder nicht.

Beide Server parallel starten

Damit ich nicht jedes Mal zwei Terminals öffnen muss, habe ich mir ein Script in der package.json eingerichtet, das beide Prozesse gleichzeitig startet:

{
  "scripts": {
    "dev": "concurrently \"catalyst serve\" \"nuxt dev\""
  }
}

Mit einem einzigen npm run dev laufen Catalyst CLI und Nuxt Dev Server parallel. Der Proxy sorgt dafür, dass alles über localhost:3000 erreichbar ist.

Wichtig: Nur im Dev-Modus aktiv

Ein Punkt, der mir wichtig war: Die Proxy-Konfiguration unter vite.server.proxy greift ausschließlich im Entwicklungsmodus. Beim Production Build (nuxt generate oder nuxt build) wird sie komplett ignoriert. Es besteht also keine Gefahr, dass lokale Proxy-Regeln versehentlich in die Produktion gelangen.

Das Catalyst SDK einbinden

Damit das Catalyst SDK im Browser verfügbar ist, binde ich zwei Scripts im app.head-Bereich meiner Nuxt-Config ein:

script: [
  {
    src: "https://static.zohocdn.com/catalyst/sdk/js/4.3.0/catalystWebSDK.js",
    type: "text/javascript",
  },
  {
    src: "/__catalyst/sdk/init.js",
    type: "text/javascript",
  },
],

Das erste Script lädt das SDK von Zohos CDN. Das zweite (/__catalyst/sdk/init.js) wird über den Proxy an die lokale Catalyst-Instanz weitergeleitet und konfiguriert das SDK mit den richtigen Projekt-Credentials.

OAuth-Login lokal testen

Der OAuth-Flow war der kniffligste Teil. Catalyst erwartet, dass Nutzer:innen nach dem Login auf eine bestimmte URL zurückgeleitet werden. Lokal bedeutet das: Der Redirect muss auf localhost:3000 zeigen, nicht auf die Catalyst-Domain.

Meine Lösung: Eine eigene Redirect-Seite, die nur lokal existiert und den Auth-Token entgegennimmt, um ihn an die eigentliche App weiterzuleiten.

Fazit

Die Kombination aus Nuxt und Zoho Catalyst funktioniert lokal hervorragend, wenn man den Vite Proxy richtig einsetzt. Die Kernidee ist simpel: Alles, was Catalyst betrifft, wird über den Proxy an die richtige Stelle geleitet – Auth-Routen an den lokalen Catalyst-Server, Function-Aufrufe an die deployed Version in der Cloud.

Das Setup erfordert etwas initiale Konfiguration, läuft danach aber stabil und erfordert keine Anpassungen mehr. Entwickler:innen können so mit vollem Hot Reload arbeiten, während Authentifizierung und Backend-Calls ganz normal funktionieren.