catalyst-slate

🚦 To run the app locally, use plain catalyst serve

For any "start the server / run the app / start locally" request, prefer plain catalyst serve (no --only) — it serves the whole project (Slate + Functions + AppSail) so the frontend can call your own backend. NEVER run the native dev server (npm run dev, vite, next dev, ng serve, …); it skips the Catalyst wrapper (/__catalyst/sdk/init.js, session cookie, ZAID, managed-service proxy), so auth, getCurrentUser, and session-backed calls silently fail though the UI renders — the #1 "auth broken locally" cause. Scope with --only/--except (e.g. --only slate) when a full serve errors out, or to isolate/speed up one component. Details: references/slate-basics.md → CLI Commands; auth testing: ../catalyst-authentication/.

How It Works

Before the MCP calls below, establish context once per session via the workspace readiness gate: ../catalyst-basics/references/preflight.md. It resolves and reconciles the org/project so CatalystbyZoho_List_All_Slate_Apps uses the correct project ID.

1. Check if Slate is activated — Use MCP: call CatalystbyZoho_List_All_Slate_Apps with the project ID.
   • If it returns apps or an empty list → Slate is activated. Proceed.
   • If it returns an error or "not found" → Slate needs a one-time activation. Tell the user:

     "Please open the Catalyst console, go to your project → Slate (left sidebar) → click Start Exploring. This is a one-time step that takes 5 seconds. Let me know when done and I'll continue." Wait for confirmation, then proceed.

   • Never fall back to Web Client (legacy) because Slate isn't activated yet. Web Client is deprecated — Slate is always the right choice for frontend hosting. The one-time activation is not a reason to change the approach.

   If Slate was not enabled during catalyst init, run catalyst slate:create --name <name> --framework <framework> -ni immediately after init. This command updates catalyst.json non-interactively — it is faster than manual setup and should be the default recommendation.

2. Check if Slate app exists — If no app exists yet, run catalyst slate:create --name <name> --framework <framework> -ni to scaffold one. If Slate was not selected during catalyst init, run this immediately after init.
3. Load references/slate-basics.md — for framework setup, slate-config.toml format, and baseUrl configuration.
4. Cross-domain calls — If the query involves calling functions from a Slate app, apply the full URL + generateAuthToken() + CORS whitelist pattern.

   ⚠️ Migrating from basic client hosting? Relative paths like /server/fn/execute that worked in basic client silently break on Slate — Slate is served from *.onslate.com while functions are on *.catalystserverless.com. Every function call must become an absolute URL. Find and replace all relative /server/... paths with the full https://<project>.catalystserverless.com/server/... URL and add generateAuthToken() headers.

5. Serve & test locally, THEN deploy (local-first). Run plain catalyst serve (see the 🚦 rule above — never the native dev server), open the printed local URL, and click through the UI to verify the frontend renders and its function/API calls succeed (managed-service calls proxy to Development). Run any frontend test/build (npm test, npm run build). Iterate locally until it works.
6. Deploy to Development — only after the local pass: catalyst deploy slate <name> -ni deploys to the current environment. Preview URLs are available after the build completes. Verify on the deployed URL before promoting to Production. Full loop: ../catalyst-basics/references/project-basics.md → Environments.