@zitadel/cli 0.3.0 → 0.4.0

package/dist/skills/zitadel-sdk-nuxt/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: zitadel-sdk-nuxt
+description: >-
+  Integrate Zitadel authentication into an existing or custom Nuxt app with
+  @zitadel/sdk-nuxt. Use when the user wants login, logout, session handling,
+  or protected routes in a Nuxt 4 app and is wiring the SDK by hand rather than
+  letting the CLI scaffold a fresh project — registering the Nuxt module,
+  reading auth state, or rendering the `<zitadel-login>` / `<zitadel-logout>`
+  components.
+---
+
+# @zitadel/sdk-nuxt
+
+A Nuxt module, Nitro middleware, and composables that add Zitadel (Nextgen)
+auth to a Nuxt 4 app. The module proxies auth traffic same-origin under
+`/__nextgen`, verifies the session JWT via JWKS on the server, seeds auth state
+into SSR and hydrates it on the client, and gates protected routes.
+
+## When to use
+
+The `zitadel` CLI (`npx @zitadel/cli@latest setup --framework nuxt`) scaffolds the module,
+plugin, login page, and `.env.local` into a fresh or detected Nuxt project —
+prefer it for greenfield work. Reach for **this skill** when you are adding auth
+to an **existing or custom** Nuxt app by hand, adjusting a scaffolded wiring, or
+wiring the middleware without the module.
+
+## Install
+
+```bash
+pnpm add @zitadel/sdk-nuxt@latest
+```
+
+Peer dependencies: `nuxt >=4`, `h3 >=1`.
+
+## Integrate
+
+The recommended path is the Nuxt module. Register it under the `nextgen` key:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@zitadel/sdk-nuxt/module'],
+  nextgen: {
+    protectedRoutes: ['/admin', '/dashboard*'], // trailing * matches sub-paths
+    loginPath: '/login',
+  },
+});
+```
+
+The module registers the Nitro middleware and auth plugin and auto-imports the
+composables — no manual `server/middleware/auth.ts`. It reads `ZITADEL_URL`,
+`NUXT_PUBLIC_ZITADEL_PROJECT_ID`, and the server-only `ZITADEL_PROJECT_SECRET`
+from the environment, or in `nuxt dev` from `.env.local` when the environment
+has none (Nuxt itself loads only `.env`). `url` and the project secret default to `ZITADEL_URL` and
+`ZITADEL_PROJECT_SECRET`; pass `nextgen.url` only to override. A built server
+reads `ZITADEL_URL` and `ZITADEL_PROJECT_SECRET` from its own runtime environment (`NUXT_NEXTGEN_URL`
+and `NUXT_NEXTGEN_PROJECT_SECRET` take precedence) and never has them baked
+into `.output/`. A `nextgen.url` or `runtimeConfig.public.zitadelProjectId` in
+`nuxt.config.ts` wins over the variables. Sessions count only in the app's own
+project, the public project id unless `nextgen.projectId` names one: with none,
+nobody is signed in.
+
+The module also loads the web components in the browser through a client-only
+plugin and provides the business copy overlay as
+`useNuxtApp().$zitadelBusinessLocales`. Do not install or import
+`@zitadel/components` in the app.
+
+Login and logout pages bind the project handle from `useZitadelProject()` inside
+`<ClientOnly>`; navigation after each flow is driven by the URL props (there is
+no `api-base` attribute):
+
+```vue
+<script setup lang="ts">
+const project = useZitadelProject();
+</script>
+
+<template>
+  <ClientOnly>
+    <zitadel-login :project="project" post-sign-in-url="/admin" />
+    <!-- on a logout page: -->
+    <zitadel-logout :project="project" post-sign-out-url="/login" />
+  </ClientOnly>
+</template>
+```
+
+Read auth state in any component via the auto-imported `useAuth()` (it omits the
+raw JWT by design). When you need the token to call upstream APIs, use
+`getAuth(event)` from `@zitadel/sdk-nuxt/server` inside a server route:
+
+```ts
+import { getAuth } from '@zitadel/sdk-nuxt/server';
+
+export default defineEventHandler((event) => {
+  const auth = getAuth(event);
+  if (!auth.isAuthenticated) throw createError({ statusCode: 401 });
+  return { userId: auth.session.userId };
+});
+```
+
+The other middleware options (`ignoredRoutes`, `audience`,
+`allowedAlgorithms`, `clockSkewMs`, the timeouts) go under `nextgen` too, and a
+built server takes each one from `NUXT_NEXTGEN_<OPTION>` (a list as JSON). Only
+an app without the module hand-rolls `server/middleware/auth.ts` with
+`createNextgenMiddleware(...)` from `@zitadel/sdk-nuxt/server`.
+
+## Widget props and events
+
+The widgets are rendered as raw custom elements, so bind their props by the element's own names, in kebab-case in a template (`post-sign-in-url`, `project-id`). The `@zitadel/sdk-vue` skill lists each prop under its wrapper name in camelCase. The table below lists the events.
+
+The widgets are plain custom elements, so each event is a DOM `CustomEvent` that carries its payload in `detail`. The events and payloads are the same ones every SPA SDK exposes as callbacks.
+
+| Widget event | Fires when | Detail | Widgets |
+| --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session |
+
+```vue
+<zitadel-login :project="project" post-sign-in-url="/admin" @zitadel-flow-complete="track" />
+```
+
+## Read these, don't guess
+
+The package README at `node_modules/@zitadel/sdk-nuxt/README.md` and the bundled
+`.d.ts` types (`dist/index.d.ts`, `dist/server.d.ts`) are authoritative and
+versioned with the installed package — read them before wiring anything, and let
+them override anything remembered. This skill teaches the pattern, not a full
+catalog of options, attributes, or the shared JWT-verification pipeline (that
+lives in `@zitadel/sdk-core`). Check the exact option names, defaults, and
+component attributes against the installed version rather than assuming.
+
+## Gotchas
+
+- **Project id is mandatory.** Without `NUXT_PUBLIC_ZITADEL_PROJECT_ID` (or
+  `runtimeConfig.public.zitadelProjectId`) the plugin silently skips
+  `configureZitadel()`, so `useZitadelProject()` is `null` and
+  `<zitadel-login>` never initializes.
+- **Do not depend on `@zitadel/components`.** The module loads the elements
+  itself; importing them in a page `<script setup>` would run during SSR, so
+  leave that to the module and wrap the elements in `<ClientOnly>`.
+- **Keep `proxyPath` at `/__nextgen` for external sign-in.** The module moves
+  the server proxy and the widgets together, but a provider returns the browser
+  to `/__nextgen/idp/{slug}/callback`, which is proxied only under the default
+  prefix.
+- **`useAuth()` never carries the JWT.** It is omitted so the token is not
+  serialized into the SSR payload; use `getAuth(event)` server-side for it.

package/dist/skills/zitadel-sdk-qwik/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: zitadel-sdk-qwik
+description: >-
+  Integrate Zitadel authentication into a Qwik app with `@zitadel/sdk-qwik`.
+  Use when the user wants to add login, logout, or a signed-in session card to
+  an existing or custom client-side Qwik SPA — wiring the `ZitadelLogin`,
+  `ZitadelLogout`, or `ZitadelSession` components and `configureZitadel`.
+---
+
+# @zitadel/sdk-qwik
+
+Qwik components that wrap the Zitadel auth UI web components (`<zitadel-login>`,
+`<zitadel-logout>`, `<zitadel-session>`) for client-side SPAs (Vite, etc.). The
+package exports the components, the `configureZitadel` handle factory, and the
+shared SPA config/handler types.
+
+## When to use
+
+- **Fresh Qwik app → use the CLI instead.** `npx @zitadel/cli@latest setup --framework qwik`
+  scaffolds auth into a new or detected Qwik project end to end (it wires this
+  SDK, the dev proxy, and config). Reach for the `zitadel-cli` skill for that.
+  Note the CLI scaffolds against **Qwik 2**, which this package also targets.
+- **This skill is for an existing or custom Qwik app** where you are adding the
+  components by hand — or adjusting a wiring the CLI already produced.
+
+## Install
+
+```sh
+pnpm add @zitadel/sdk-qwik@latest
+```
+
+The package declares a peer dependency on `@qwik.dev/core` (`^2.0.0-beta.45`),
+so the host app must be on **Qwik 2**. TypeScript ≥ 5.0 is required — the
+published types re-export with `export type *`, a 5.0 feature.
+
+## Integrate
+
+Build a project handle with `configureZitadel`, then render a component with it:
+
+```tsx
+import { component$ } from '@qwik.dev/core';
+import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-qwik';
+
+export default component$(() => {
+  const project = configureZitadel({
+    projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+    proxyPath: '/__nextgen',
+  });
+
+  return <ZitadelLogin project={project} purpose="login" postSignInUrl="/" />;
+});
+```
+
+- `<ZitadelLogout project={project} postSignOutUrl="/login" />` works the same way.
+- `<ZitadelSession project={project} />` renders the signed-in session card.
+- Instead of the `project` handle you may pass the discrete `projectId` /
+  `proxyPath` props; the widget uses whichever is present.
+- Widget events are optional QRL callbacks; see Widget props and events.
+- The SDK binds `project` (and `projectId` / `proxyPath`) to the element as DOM
+  *properties*, matching the other framework SDKs.
+
+## Widget props and events
+
+`ZitadelLogin`, `ZitadelLogout` and `ZitadelSession` take the props below, spelled the same in every SPA SDK. An unset prop keeps the widget's own default.
+
+| Prop | Type | Default | Widgets | Description |
+| --- | --- | --- | --- | --- |
+| `project` | `ZitadelProject` | unset | Login, Logout, Session | The handle from `configureZitadel(...)`. Wins over `projectId` and `proxyPath`. |
+| `projectId` | `string` | unset | Login, Logout, Session | Project id, read when no `project` handle is passed. |
+| `proxyPath` | `string` | `"/__nextgen"` | Login, Logout, Session | Same-origin path the widget calls. |
+| `purpose` | `CreateFlowBodyPurpose` | `"login"` | Login | Flow purpose. |
+| `flowName` | `string` | unset | Login | Runs the flow definition with this `name`; unset runs the project's default flow for the purpose. |
+| `postSignInUrl` | `string` | unset | Login | Where to navigate after a completed sign-in. When the page's `next` query parameter names a path on the same origin, as the server SDKs' middleware sets it for a signed-out visit to a protected route, the widget returns there instead. |
+| `forcePostSignInUrl` | `boolean` | `false` | Login | Navigates to `postSignInUrl` even when the page's `next` query parameter names a path, for a page that uses `next` for something of its own. |
+| `postSignOutUrl` | `string` | unset | Logout, Session | Where to navigate after sign-out. |
+| `resumeFlowId` | `string` or `null` | unset | Login | An existing flow's id to resume instead of starting a new flow; unset, `null` or `""` falls back to the `flow` query parameter, and an id that no longer resolves starts a new flow. |
+| `variant` | `"widget"` or `"page"` | `"widget"` | Login, Session | `widget` is content-sized and paints no page chrome; `page` claims the viewport, paints the surface background and loads the brand font, and on Login focuses the first field. |
+| `theme` | `"light"`, `"dark"` or `"auto"` | unset | Login, Logout, Session | Colour mode. Unset follows the tenant's branding theme on Login, then the variant default (`dark` for `page`, `auto` for `widget`); Logout defaults to `auto`. `auto` follows `prefers-color-scheme`. |
+| `suppressHeader` | `boolean` | `false` | Login, Session | Visually hides the widget's own heading block while keeping it in the accessibility tree, for pages that already carry the heading. |
+| `suppressPasswordToggle` | `boolean` | `false` | Login | Hides the show/hide button on password fields. |
+| `heading` | `string` | `"Signed in as"` | Session | Heading text override. |
+| `logoutLabel` | `string` | `"Sign out"` | Session | Logout action label override. |
+| `locales` | `Record<string, Partial<Record<string, string>>>` | unset | Login | Copy overrides merged over the builtin dictionaries, keyed by primary language subtag, for example `{ en: { "identifier.title": "Welcome back" } }`. |
+| `lang` | `string` | browser language | Login | BCP-47 language override. |
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `onFlowStep$` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `onFlowInput$` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `onFlowComplete$` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `onFlowRedirect$` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `onFlowError$` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `onSignout$` |
+
+```tsx
+<ZitadelLogin project={project} theme="light" onFlowComplete$={(detail) => track(detail)} />
+```
+
+When your callback for `zitadel-flow-complete`, `zitadel-flow-redirect` or `zitadel-signout` returns a promise, the widget waits for it to settle (up to two seconds) before it navigates.
+
+## Read these, don't guess
+
+Confirm the current surface before wiring — do not rely on memory:
+
+- `node_modules/@zitadel/sdk-qwik/README.md` — the installed package's own usage
+  notes (proxying, deployment status) are authoritative over this skill.
+- The package's `.d.ts` types (`node_modules/@zitadel/sdk-qwik/dist/index.d.ts`)
+  are the source of truth for exports and prop names. The named exports are
+  `ZitadelLogin`, `ZitadelLogout`, `ZitadelSession`, `configureZitadel`,
+  `getApi`, `getZitadelConfig`, and `businessLocales`; prop types
+  (`ZitadelLoginProps`, etc.) and the shared SPA config/handler types are
+  re-exported there. Check props (`purpose`, `variant`, `theme`, `flowName`,
+  `locales`, `lang`, `ref`, …) against the types rather than assuming them.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, pass `projectId` and `proxyPath` to the `ZitadelLogin` wrapper as strings (it writes them as the `project-id` and `proxy-path` attributes; use those hyphenated names only on a raw `<zitadel-login>` element), because a widget that starts before its configuration arrives shows an error instead of the flow. `ZitadelLogout` and `ZitadelSession` do the same, and the other string and boolean options (`purpose`, `flowName`, `postSignInUrl`, `forcePostSignInUrl`, `resumeFlowId`, `postSignOutUrl`, `variant`, `theme`, `heading`, `logoutLabel`, `lang`, `suppressHeader`, `suppressPasswordToggle`) are written as attributes too. A `project` handle contributes its `projectId`, `proxyPath`, `url` and `publishableKey` as attributes; the rest of the handle, and `locales`, are set as element properties after hydration, so a widget that needs `locales` still gets them only on the client.
+- **Qwik 2 only.** The peer dep is `@qwik.dev/core ^2.0.0-beta.45` and imports
+  come from `@qwik.dev/core` (not `@builder.io/qwik`). A Qwik 1 app will not
+  satisfy the peer range.
+- **Proxying is same-origin.** The widgets call `${proxyPath}/…` same-origin
+  (default `/__nextgen`). The CLI dev proxy covers local development. Per the
+  README, **production SPA deployment is not yet supported** — the same-origin
+  path must come from your hosting platform, and the CLI cannot scaffold those
+  configs yet.
+- **Local dev without the proxy.** You can point `proxyPath` straight at the
+  backend cross-origin, e.g. `proxyPath: 'http://localhost:8080'` (the
+  `zitadel start` local runtime default port).
+- **Properties and attributes.** Qwik 2 binds custom-element JSX props as
+  lower-cased attributes only, so the wrapper writes string and boolean config
+  as kebab-case attributes (present in server markup) and applies all config,
+  including property-only values such as `locales`, as DOM properties on the
+  client — which is why the SDK wrapper exists rather than using the web
+  components directly.

package/dist/skills/zitadel-sdk-qwik-router/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: zitadel-sdk-qwik-router
+description: >-
+  Integrate Zitadel authentication into an existing or custom Qwik Router app with
+  @zitadel/sdk-qwik-router. Use when the user wants login, logout, session
+  handling, or protected routes in a Qwik 2 (Qwik Router) app and is wiring the
+  SDK by hand rather than letting the CLI scaffold a fresh project — adding the
+  request handler, reading auth state in a `routeLoader$`, or rendering the
+  `ZitadelLogin` / `ZitadelSession` widgets.
+---
+
+# @zitadel/sdk-qwik-router
+
+A Qwik Router request handler and helpers that add Zitadel (Nextgen) auth to a
+Qwik 2 app. The handler proxies auth traffic same-origin under `/__nextgen`,
+verifies the session JWT via JWKS on the server, stores the result on
+`requestEvent.sharedMap`, and redirects unauthenticated requests on protected
+routes. The package is server-only; the widgets come from `@zitadel/sdk-qwik`.
+
+## When to use
+
+The `zitadel` CLI (`zitadel setup --framework qwik-router`) scaffolds the handler
+plugin, login/register/profile routes, and `.env.local` into a fresh or detected
+Qwik Router project — prefer it for greenfield work. Reach for **this skill** when
+you are adding auth to an **existing or custom** Qwik Router app by hand, or
+adjusting a scaffolded wiring.
+
+## Install
+
+```bash
+pnpm add -D @zitadel/sdk-qwik-router@latest
+# the login/logout/session widgets are a separate package:
+pnpm add -D @zitadel/sdk-qwik@latest
+```
+
+Install both as **dev dependencies**: Qwik bundles `devDependencies` into the
+server build and leaves `dependencies` external. Peer deps: `@qwik.dev/core` and
+`@qwik.dev/router`, both `^2.0.0-beta.45`. A Qwik 1 app (`@builder.io/qwik-city`)
+must migrate to `@qwik.dev/*` first.
+
+## Integrate
+
+**1. Request handler.** Add a root plugin, e.g. `src/routes/plugin@nextgen.ts`:
+
+```ts
+import { createNextgenOnRequest } from '@zitadel/sdk-qwik-router/server';
+
+export const onRequest = createNextgenOnRequest({
+  protectedRoutes: ['/admin', '/dashboard*'], // trailing * matches sub-paths
+  loginPath: '/login',
+});
+```
+
+`url` and `projectSecret` default to `ZITADEL_URL` and `ZITADEL_PROJECT_SECRET`,
+read per request from Qwik Router's `requestEvent.env` (where Vite loads
+`.env.local`), falling back to `process.env`; pass them only to override.
+Sessions count only in the app's own project: `projectId`, else
+`ZITADEL_PROJECT_ID`, else `PUBLIC_ZITADEL_PROJECT_ID`, read the same way. With
+none set, nobody is signed in. To run
+alongside your own handler, export an array: `[createNextgenOnRequest({...}), myOnRequest]`.
+
+**2. Read auth server-side** with `getAuth(ev)` in a `routeLoader$`, action, or
+endpoint:
+
+```ts
+import { routeLoader$ } from '@qwik.dev/router';
+import { getAuth } from '@zitadel/sdk-qwik-router/server';
+
+export const useUser = routeLoader$((ev) => {
+  const auth = getAuth(ev);
+  if (!auth.isAuthenticated) throw ev.redirect(302, '/login');
+  return { userId: auth.session.userId };
+});
+```
+
+`protectedRoutes` only guards full page loads. To keep a route from rendering at
+all without a session, export a loader like this one from the route itself —
+Qwik Router runs it on the server for `<Link>` navigation too.
+
+**3. Render the widgets** from `@zitadel/sdk-qwik`:
+
+```tsx
+import { component$ } from '@qwik.dev/core';
+import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-qwik';
+
+const project = configureZitadel({
+  projectId: import.meta.env.PUBLIC_ZITADEL_PROJECT_ID,
+  proxyPath: '/__nextgen',
+});
+
+export default component$(() => (
+  <ZitadelLogin project={project} purpose="login" postSignInUrl="/admin" />
+));
+```
+
+`<ZitadelSession project={project} postSignOutUrl="/login" />` renders the
+signed-in card with sign-out, and `<ZitadelLogout>` a sign-out control on its own.
+
+## Widget props and events
+
+This SDK is server-only. The widgets come from `@zitadel/sdk-qwik`, so read its skill for the widget props and events.
+
+## Read these, don't guess
+
+The package README at `node_modules/@zitadel/sdk-qwik-router/README.md` and the
+bundled `.d.ts` types (`dist/server.d.ts`, `dist/client.d.ts`) are authoritative
+and versioned with the installed package — read them before wiring anything, and
+let them override anything remembered. This skill teaches the pattern, not a
+full catalog of options or the shared JWT-verification pipeline (that lives in
+`@zitadel/sdk-core`). For widget props and QRL callbacks, read
+`node_modules/@zitadel/sdk-qwik/README.md` and its types. Check exact option
+names and defaults against the installed version rather than assuming.
+
+## Gotchas
+
+- **Qwik 2 only.** Imports come from `@qwik.dev/core` and `@qwik.dev/router`
+  (not `@builder.io/qwik-city`); a Qwik 1 app will not satisfy the peer range.
+- **Dev dependency, not dependency.** Qwik's starter `vite.config.ts` throws if a
+  package is listed in both sections, and a regular dependency stays external to
+  the server bundle.
+- **`@zitadel/sdk-qwik-router` renders no widgets.** They come from
+  `@zitadel/sdk-qwik`.
+- **Env comes from `requestEvent.env`.** Vite loads `.env.local` there, not onto
+  `process.env`, so the handler reads it per request.
+- **Client-side `<Link>` navigation skips the handler.** Without a route
+  loader guard, only the `ZitadelSession` card sends a signed-out visitor away.

package/dist/skills/zitadel-sdk-react/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: zitadel-sdk-react
+description: >-
+  Integrate Zitadel authentication into an existing React app with
+  `@zitadel/sdk-react`. Use when adding Zitadel login, registration, logout, or
+  session handling to a client-side React / Vite SPA or a TanStack
+  (Router/Start) app — wiring the `ZitadelLogin`, `ZitadelLogout`, and
+  `ZitadelSession` auth-UI components into pages you already have.
+---
+
+# @zitadel/sdk-react
+
+React wrappers around the Zitadel auth-UI web components, for client-side SPAs.
+
+## When to use
+
+Use this skill to drop the Zitadel auth UI into an **existing or custom** React
+app — your own routes, your own bundler (Vite, TanStack Start, etc.) — by
+rendering the SDK's components on your login/profile pages.
+
+If the user instead wants a **fresh** app scaffolded, the CLI does that:
+`npx @zitadel/cli@latest setup --framework react` generates a wired React project. Reach for
+this skill when there is already an app to integrate into and the CLI's
+scaffolding would overwrite or not fit it.
+
+## Install
+
+```sh
+npm install @zitadel/sdk-react@latest
+```
+
+Peer dependencies: `react >=18` and `react-dom >=18`. Requires TypeScript ≥ 5.0 (the published types use `export type *`).
+
+## Integrate
+
+Call `configureZitadel(...)` once before rendering and pass the returned handle
+as the `project` prop. The SPA renders after configuration, so the handle is
+present when the underlying web component upgrades.
+
+```tsx
+import {
+  ZitadelLogin,
+  ZitadelLogout,
+  ZitadelSession,
+  configureZitadel,
+} from "@zitadel/sdk-react";
+
+// Configure once, module scope, before rendering.
+const project = configureZitadel({
+  projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID, // or your env source
+  proxyPath: "/__nextgen", // same-origin path your deploy proxies to the backend
+});
+
+export function LoginPage() {
+  return <ZitadelLogin project={project} purpose="login" postSignInUrl="/" />;
+}
+
+export function ProfilePage() {
+  return (
+    <>
+      <ZitadelSession project={project} />
+      <ZitadelLogout project={project} postSignOutUrl="/login" />
+    </>
+  );
+}
+```
+
+- `purpose` defaults to `"login"`; set it for other flows.
+- `postSignInUrl` / `postSignOutUrl` are where the widget sends the user after
+  the flow completes.
+- The widget's `zitadel-*` events reach you as the `on*` callbacks listed under
+  Widget props and events.
+
+## Widget props and events
+
+`ZitadelLogin`, `ZitadelLogout` and `ZitadelSession` take the props below, spelled the same in every SPA SDK. An unset prop keeps the widget's own default.
+
+| Prop | Type | Default | Widgets | Description |
+| --- | --- | --- | --- | --- |
+| `project` | `ZitadelProject` | unset | Login, Logout, Session | The handle from `configureZitadel(...)`. Wins over `projectId` and `proxyPath`. |
+| `projectId` | `string` | unset | Login, Logout, Session | Project id, read when no `project` handle is passed. |
+| `proxyPath` | `string` | `"/__nextgen"` | Login, Logout, Session | Same-origin path the widget calls. |
+| `purpose` | `CreateFlowBodyPurpose` | `"login"` | Login | Flow purpose. |
+| `flowName` | `string` | unset | Login | Runs the flow definition with this `name`; unset runs the project's default flow for the purpose. |
+| `postSignInUrl` | `string` | unset | Login | Where to navigate after a completed sign-in. When the page's `next` query parameter names a path on the same origin, as the server SDKs' middleware sets it for a signed-out visit to a protected route, the widget returns there instead. |
+| `forcePostSignInUrl` | `boolean` | `false` | Login | Navigates to `postSignInUrl` even when the page's `next` query parameter names a path, for a page that uses `next` for something of its own. |
+| `postSignOutUrl` | `string` | unset | Logout, Session | Where to navigate after sign-out. |
+| `resumeFlowId` | `string` or `null` | unset | Login | An existing flow's id to resume instead of starting a new flow; unset, `null` or `""` falls back to the `flow` query parameter, and an id that no longer resolves starts a new flow. |
+| `variant` | `"widget"` or `"page"` | `"widget"` | Login, Session | `widget` is content-sized and paints no page chrome; `page` claims the viewport, paints the surface background and loads the brand font, and on Login focuses the first field. |
+| `theme` | `"light"`, `"dark"` or `"auto"` | unset | Login, Logout, Session | Colour mode. Unset follows the tenant's branding theme on Login, then the variant default (`dark` for `page`, `auto` for `widget`); Logout defaults to `auto`. `auto` follows `prefers-color-scheme`. |
+| `suppressHeader` | `boolean` | `false` | Login, Session | Visually hides the widget's own heading block while keeping it in the accessibility tree, for pages that already carry the heading. |
+| `suppressPasswordToggle` | `boolean` | `false` | Login | Hides the show/hide button on password fields. |
+| `heading` | `string` | `"Signed in as"` | Session | Heading text override. |
+| `logoutLabel` | `string` | `"Sign out"` | Session | Logout action label override. |
+| `locales` | `Record<string, Partial<Record<string, string>>>` | unset | Login | Copy overrides merged over the builtin dictionaries, keyed by primary language subtag, for example `{ en: { "identifier.title": "Welcome back" } }`. |
+| `lang` | `string` | browser language | Login | BCP-47 language override. |
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `onFlowStep` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `onFlowInput` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `onFlowComplete` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `onFlowRedirect` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `onFlowError` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `onSignout` |
+
+```tsx
+<ZitadelLogin project={project} theme="light" onFlowComplete={(detail) => track(detail)} />
+```
+
+When your callback for `zitadel-flow-complete`, `zitadel-flow-redirect` or `zitadel-signout` returns a promise, the widget waits for it to settle (up to two seconds) before it navigates.
+
+## Read these, don't guess
+
+This skill is the integration **pattern**, not an API catalog — exact names,
+props, and defaults are authoritative only at the source. Before relying on a
+specific prop or export, read:
+
+- `node_modules/@zitadel/sdk-react/README.md` — the installed package's own docs.
+- The package's TypeScript types (`node_modules/@zitadel/sdk-react/dist/index.d.ts`
+  and its re-exported `@zitadel/sdk-core/types`) — the authoritative list of
+  exported components, props, and event-detail shapes.
+
+Discover from those rather than assuming; the package and this skill version
+independently and a hardcoded API list here would drift.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration, or pass `project-id` and `proxy-path` to the `ZitadelLogin` wrapper as strings (they are written into the server markup as attributes), because a widget that starts before its configuration arrives shows an error instead of the flow. React 19 does not apply an object property such as `project` while hydrating a server-rendered custom element, so on a server-rendered page pass `project-id` and `proxy-path` as strings instead of a `project` handle.
+- **TypeScript ≥ 5.0 required** — the published types use `export type *`, which
+  older TypeScript cannot parse.
+- **Browser web components.** These wrap browser web components that only start
+  in the browser. A server render emits a bare element, so follow the
+  server-rendering gotcha above: string `project-id` and `proxy-path` may be
+  server-rendered, while an object such as `project` is client-only because
+  React 19 does not apply object properties while hydrating.
+- **Same-origin proxy.** The widgets call `${proxyPath}/…` same-origin (default
+  `/__nextgen`). Your deployment must proxy that path to the Zitadel backend.
+  Production SPA deployment is not yet fully supported — see
+  [ADR 036](https://github.com/zitadel/nextgen/blob/main/docs/adrs/036-api-credential-planes.md)
+  and [zitadel/nextgen#560](https://github.com/zitadel/nextgen/issues/560). The
+  CLI dev proxy covers local development.
+- **Local dev without a proxy.** You can point `proxyPath` straight at the
+  backend cross-origin, e.g. `proxyPath: "http://localhost:8080"` (the
+  `zitadel start` default port).
+- **Configure before render.** Build the handle with `configureZitadel(...)` at
+  module scope and pass it as `project`, so it is set when the element upgrades.