feat: scaffold React, Vue, Angular, and Nuxt apps from the CLI

Adds setup --framework react|vue|angular|nuxt to @zitadel/cli. Each framework
scaffolds its auth entry/pages and wires a dev proxy forwarding /__nextgen to the
backend with an sk_<project_id> bearer: a Vite config merge for React/Vue, a
proxy.conf.cjs wired into angular.json for Angular, and the @zitadel/sdk-nuxt
module for Nuxt. Adds a --dev-port flag and the supporting detectors,
scaffolders, and patchers.

Author: mridang

.changeset/cli-spa-frameworks.md

@@ -0,0 +1,5 @@
+---
+"@zitadel/cli": minor
+---
+
+Add `setup --framework react|vue|angular|nuxt` support to the CLI. Each framework scaffolds its auth entry/pages and wires `/__nextgen/*` calls to the backend with a `sk_<project_id>` bearer attached: React and Vue get a dev proxy magicast-merged into the Vite config (`vite.config.*`) that reads the project id from `ZITADEL_PROJECT_ID`; Angular gets a `proxy.conf.cjs` wired into `angular.json` that reads it from `zitadel.json`; and Nuxt registers the `@zitadel/sdk-nuxt` module in the Nuxt config (`nuxt.config.*`), which adds the proxy via server middleware. A `--dev-port` flag sets the scaffolded dev-server port.

apps/cli/README.md

@@ -1,6 +1,6 @@
 # @zitadel/cli
 
-Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js app.
+Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js, React, Vue, Angular, or Nuxt app.
 
 ```sh
 npx @zitadel/cli@alpha start
@@ -74,44 +74,43 @@ passkey can sign in with either credential.
 <summary>Full command reference</summary>
 
 <!-- commands -->
-
-- [`zitadel apply`](#zitadel-apply)
-- [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
-- [`zitadel commands`](#zitadel-commands)
-- [`zitadel doctor`](#zitadel-doctor)
-- [`zitadel eject`](#zitadel-eject)
-- [`zitadel help [COMMAND]`](#zitadel-help-command)
-- [`zitadel logs`](#zitadel-logs)
-- [`zitadel plan`](#zitadel-plan)
-- [`zitadel reset`](#zitadel-reset)
-- [`zitadel search`](#zitadel-search)
-- [`zitadel setup`](#zitadel-setup)
-- [`zitadel start`](#zitadel-start)
-- [`zitadel status`](#zitadel-status)
-- [`zitadel stop`](#zitadel-stop)
-- [`zitadel uninstall`](#zitadel-uninstall)
-- [`zitadel version`](#zitadel-version)
-- [`zitadel which`](#zitadel-which)
+* [`zitadel apply`](#zitadel-apply)
+* [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
+* [`zitadel commands`](#zitadel-commands)
+* [`zitadel doctor`](#zitadel-doctor)
+* [`zitadel eject`](#zitadel-eject)
+* [`zitadel help [COMMAND]`](#zitadel-help-command)
+* [`zitadel logs`](#zitadel-logs)
+* [`zitadel plan`](#zitadel-plan)
+* [`zitadel reset`](#zitadel-reset)
+* [`zitadel search`](#zitadel-search)
+* [`zitadel setup`](#zitadel-setup)
+* [`zitadel start`](#zitadel-start)
+* [`zitadel status`](#zitadel-status)
+* [`zitadel stop`](#zitadel-stop)
+* [`zitadel uninstall`](#zitadel-uninstall)
+* [`zitadel version`](#zitadel-version)
+* [`zitadel which`](#zitadel-which)
 
 ## `zitadel apply`
 
 Validate and upload repo config to the platform.
 
 ```
 USAGE
-  $ zitadel apply [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [-e development|preview|production]
+  $ zitadel apply [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [-e
+    development|preview|production]
 
 FLAGS
-  -c, --cwd=<value>                 Project directory to operate on.
-  -e, --environment=<option>        Target environment (default: development).
-                                    <options: development|preview|production>
-  -f, --force                       Overwrite protected files on conflict.
-  -n, --non-interactive             Disable prompts. Required when scripting or running as an agent.
-  -s, --server=<value>              Override the resolved server URL.
-      --debug                       Debug logging.
-      --dry-run                     Preview without mutating files or the platform.
-      --verbose                     Verbose logging.
+  -c, --cwd=<value>           Project directory to operate on.
+  -e, --environment=<option>  Target environment (default: development).
+                              <options: development|preview|production>
+  -f, --force                 Overwrite protected files on conflict.
+  -n, --non-interactive       Disable prompts. Required when scripting or running as an agent.
+  -s, --server=<value>        Override the resolved server URL.
+      --debug                 Debug logging.
+      --dry-run               Preview without mutating files or the platform.
+      --verbose               Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -288,19 +287,19 @@ Validate config without mutation and preview the sync diff.
 
 ```
 USAGE
-  $ zitadel plan [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [-e development|preview|production]
+  $ zitadel plan [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [-e
+    development|preview|production]
 
 FLAGS
-  -c, --cwd=<value>                 Project directory to operate on.
-  -e, --environment=<option>        Target environment (default: development).
-                                    <options: development|preview|production>
-  -f, --force                       Overwrite protected files on conflict.
-  -n, --non-interactive             Disable prompts. Required when scripting or running as an agent.
-  -s, --server=<value>              Override the resolved server URL.
-      --debug                       Debug logging.
-      --dry-run                     Preview without mutating files or the platform.
-      --verbose                     Verbose logging.
+  -c, --cwd=<value>           Project directory to operate on.
+  -e, --environment=<option>  Target environment (default: development).
+                              <options: development|preview|production>
+  -f, --force                 Overwrite protected files on conflict.
+  -n, --non-interactive       Disable prompts. Required when scripting or running as an agent.
+  -s, --server=<value>        Override the resolved server URL.
+      --debug                 Debug logging.
+      --dry-run               Preview without mutating files or the platform.
+      --verbose               Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -356,17 +355,19 @@ Create a Zitadel project and scaffold local auth.
 ```
 USAGE
   $ zitadel setup [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [--framework next] [--renderer react|web-component] [--skip-install]
+    [--framework next|nuxt|react|vue|angular] [--renderer react|web-component] [--dev-port <value>] [--skip-install]
 
 FLAGS
   -c, --cwd=<value>         Project directory to operate on.
   -f, --force               Overwrite protected files on conflict.
   -n, --non-interactive     Disable prompts. Required when scripting or running as an agent.
   -s, --server=<value>      Override the resolved server URL.
       --debug               Debug logging.
+      --dev-port=<value>    Dev-server port; also the issuer origin registered with Zitadel. Defaults to the detected
+                            port. Use distinct ports to run several scaffolded apps side by side.
       --dry-run             Preview without mutating files or the platform.
       --framework=<option>  Framework to target.
-                            <options: next>
+                            <options: next|nuxt|react|vue|angular>
       --renderer=<option>   Renderer (default: react).
                             <options: react|web-component>
       --skip-install        Do not install dependencies after setup updates package.json.
@@ -380,6 +381,8 @@ DESCRIPTION
 
 EXAMPLES
   $ zitadel setup --framework next
+
+  $ zitadel setup --framework react --dev-port 3000
 ```
 
 ## `zitadel start`
@@ -537,7 +540,6 @@ EXAMPLES
 ```
 
 _See code: [@oclif/plugin-which](https://github.com/oclif/plugin-which/blob/3.2.55/src/commands/which.ts)_
-
 <!-- commandsstop -->
 
 </details>

apps/cli/SKILLS.md

@@ -4,8 +4,8 @@ description: >-
   Set up and manage Zitadel authentication in a local project with the
   agent-friendly `zitadel` CLI. Use when the user wants to add login,
   registration, or session handling, create a Zitadel project, scaffold auth
-  routes for a Next.js App Router app, or plan and apply Zitadel config changes
-  from repo state.
+  for a Next.js, React, Vue, Angular, or Nuxt app, or plan and apply Zitadel
+  config changes from repo state.
 ---
 
 # Zitadel CLI
@@ -56,7 +56,12 @@ layer, not the envelope.
   and login flow are provisioned server-side at creation, so setup neither
   scaffolds nor uploads them. Agents must pass `--framework` when scaffolding
   into a fresh directory; interactive humans can omit it and choose from the
-  prompt. Flags: `--framework`, `--renderer`.
+  prompt. Flags: `--framework next|react|vue|angular|nuxt`, `--renderer
+  react|web-component` (selects the Next.js auth-page renderer; accepted for any
+  framework and recorded in `zitadel.json` branding, but only Next varies its
+  generated templates by it), `--dev-port` (dev-server port, also the issuer
+  origin registered with Zitadel — use distinct ports to run several scaffolded
+  apps side by side), `--skip-install`.
 - `plan` — validate config and preview the sync diff without mutating anything.
 - `apply` — validate and upload repo config to the platform.
 - `doctor` — verify generated app files and local state once `zitadel.json`

apps/cli/package.json

@@ -61,6 +61,7 @@
     "@zitadel/api": "workspace:*",
     "ajv": "catalog:",
     "consola": "^3.4.2",
+    "magicast": "^0.5.3",
     "safe-stable-stringify": "catalog:",
     "zod": "catalog:",
     "picocolors": "^1.1.1"

apps/cli/src/commands/eject.ts

@@ -21,6 +21,7 @@ async function resolveEjectActions(cwd: string): Promise<EjectActions> {
     directories: [".zitadel"],
     envBackups: [".env.local"],
     dependencies: [],
+    configEdits: [],
   };
   const orca = createOrca();
   const framework = await orca.tryDetect(cwd);
@@ -155,7 +156,21 @@ export default class Eject extends BaseCommand {
       removed.push(rel);
     }
 
-    if (removed.length === 0 && backedUp.length === 0) {
+    // In-place config merges (vite.config.ts / angular.json / nuxt.config.ts)
+    // can't be auto-reverted, so surface them as manual cleanup steps. The
+    // Angular patcher also edits package.json (a `dev` script, not a config
+    // block), so word that one accurately.
+    const manualSteps = actions.configEdits.map((rel) => {
+      if (rel === "package.json" || rel.endsWith("/package.json")) {
+        return `Remove the "dev" script setup added to ${rel}`;
+      }
+      if (rel === "angular.json" || rel.endsWith("/angular.json")) {
+        return `Remove the Zitadel proxyConfig (and dev-server port) from the serve target in ${rel}`;
+      }
+      return `Remove the Zitadel configuration block from ${rel}`;
+    });
+
+    if (removed.length === 0 && backedUp.length === 0 && manualSteps.length === 0) {
       return this.emit({ status: "skipped", reason: "nothing-to-eject", data: { cwd } });
     }
 
@@ -169,6 +184,7 @@ export default class Eject extends BaseCommand {
         files_preserved: preserved,
         backed_up: backedUp,
         next_commands: nextCommands,
+        manual_steps: manualSteps,
       },
     });
   }

apps/cli/src/commands/setup/index.ts

@@ -49,13 +49,20 @@ const FRAMEWORK_OPTIONS = createOrca()
  */
 export default class Setup extends BaseCommand {
   static override description = "Create a Zitadel project and scaffold local auth.";
-  static override examples = ["<%= config.bin %> setup --framework next"];
+  static override examples = [
+    "<%= config.bin %> setup --framework next",
+    "<%= config.bin %> setup --framework react --dev-port 3000",
+  ];
   static override flags = {
     framework: Flags.string({ description: "Framework to target.", options: FRAMEWORK_OPTIONS }),
     renderer: Flags.string({
       description: "Renderer (default: react).",
       options: [...RENDERER_IDS],
     }),
+    "dev-port": Flags.integer({
+      description:
+        "Dev-server port; also the issuer origin registered with Zitadel. Defaults to the detected port. Use distinct ports to run several scaffolded apps side by side.",
+    }),
     "skip-install": Flags.boolean({
       description: "Do not install dependencies after setup updates package.json.",
     }),
@@ -103,33 +110,66 @@ export default class Setup extends BaseCommand {
       }
     }
 
+    // An explicit --dev-port overrides the detected port for the whole run, so
+    // the issuer and the registered origin track the requested port (and several
+    // apps can be scaffolded on distinct ports). The config edits set the
+    // dev-server port only when it is unset, so a project that already pins a
+    // different port in vite.config.*/angular.json keeps it — pass --dev-port to
+    // match that pin (or remove it) if the origin check rejects requests.
+    if (flags["dev-port"] !== undefined) {
+      const devPort = flags["dev-port"];
+      if (!Number.isInteger(devPort) || devPort < 1 || devPort > 65535) {
+        throw new ZitadelError(
+          "E_VALIDATION",
+          `--dev-port must be an integer in 1..65535, got ${devPort}`,
+        );
+      }
+      framework = {
+        ...framework,
+        devPort,
+        url: issuerFromPort(devPort),
+      };
+    }
+
     let answers: SetupAnswers = {
       server: this.meta.source,
       devPort: framework.devPort,
     };
 
     if (!nonInteractive && !dryRun) {
       intro("Zitadel setup");
-      const promptCtx = { framework, serverFlag: this.meta.serverFlag };
+      const promptCtx = {
+        framework,
+        serverFlag: this.meta.serverFlag,
+        devPortFromFlag: flags["dev-port"] !== undefined,
+      };
       for (const prompt of SETUP_PROMPTS) {
         answers = await prompt.ask(answers, promptCtx);
       }
       outro("Configuration captured");
     }
 
     const issuer = issuerFromPort(answers.devPort);
+    // The DevPortPrompt can change the port interactively, so fold the answer
+    // back into the framework: the patched dev-server config reads
+    // `framework.devPort`, and it must agree with the issuer and the registered
+    // origin (both derived from `answers.devPort`).
+    framework = { ...framework, devPort: answers.devPort, url: issuer };
 
     // `POST /projects` is unauthenticated. Creating the project also
     // provisions its default user schema and login flow server-side, so the
     // CLI no longer builds, scaffolds, or uploads those resources here.
     consola.start(`Creating project on ${answers.server}${dryRun ? " (dry run)" : ""}`);
     const unauthClient = createZitadelClient({ baseUrl: answers.server });
+    // Register the app's own origin so the backend's origin check allows
+    // requests the dev proxy forwards from it.
     const project = dryRun
-      ? dryRunProject()
+      ? dryRunProject(issuer)
       : await createProjectWithLocalHint(
           unauthClient,
           answers.server,
           this.meta.cliVersion,
+          issuer,
         );
     consola.success(`Created project ${project.id}`);
 
@@ -235,12 +275,12 @@ async function resolveScaffoldFramework(
 }
 
 /** A deterministic stand-in project for `--dry-run`, so no remote call is made. */
-function dryRunProject(): CreateProject201 {
+function dryRunProject(issuer: string): CreateProject201 {
   return {
     id: "dry-run-0000",
     projectSecret: "sk_proj_dry_run_full",
     previewSecret: "sk_proj_dry_run_preview",
-    previewOrigins: [],
+    previewOrigins: [issuer],
     createdAt: "2026-04-21T14:03:11.000Z",
   };
 }
@@ -249,9 +289,12 @@ async function createProjectWithLocalHint(
   client: ReturnType<typeof createZitadelClient>,
   server: string,
   cliVersion: string,
+  issuer: string,
 ): Promise<CreateProject201> {
   try {
-    return await client.createProject({ previewOrigins: [] });
+    // Register the app's own origin so the backend's origin check allows the
+    // requests the dev proxy forwards from it.
+    return await client.createProject({ previewOrigins: [issuer] });
   } catch (error) {
     const normalized = toZitadelError(error);
     throw new ZitadelError(normalized.code, normalized.message, {

apps/cli/src/commands/setup/prompts/dev-port.ts

@@ -8,7 +8,13 @@ import type { PromptContext, SetupAnswers, SetupPrompt } from "./types";
  * becomes the issuer URL (`http://localhost:<port>`) via `issuerFromPort`.
  */
 export class DevPortPrompt implements SetupPrompt {
-  async ask(answers: SetupAnswers, _ctx: PromptContext): Promise<SetupAnswers> {
+  async ask(answers: SetupAnswers, ctx: PromptContext): Promise<SetupAnswers> {
+    // `--dev-port <n>` is authoritative: skip the prompt so an interactive
+    // answer can't override the explicit flag (the base command already folded
+    // it into answers.devPort).
+    if (ctx.devPortFromFlag) {
+      return answers;
+    }
     const value = await text({
       message: "Dev server port",
       placeholder: String(answers.devPort),

apps/cli/src/commands/setup/prompts/types.ts

@@ -28,6 +28,12 @@ export type PromptContext = {
    * passed a flag" from "we fell back to the cloud default".
    */
   readonly serverFlag?: string;
+  /**
+   * Whether `--dev-port` was passed explicitly. When set, the flag is
+   * authoritative and {@link import("./dev-port").DevPortPrompt} skips itself so
+   * an interactive answer can't override a scripted/flagged port.
+   */
+  readonly devPortFromFlag?: boolean;
 };
 
 /**