@zitadel/cli 0.3.0 → 0.4.0

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

@@ -0,0 +1,144 @@
+---
+name: zitadel-sdk-solid
+description: >-
+  Integrate Zitadel authentication into a SolidJS app with
+  `@zitadel/sdk-solid`. Use when the user wants to add Zitadel login,
+  registration, logout, or a signed-in session card to an existing or
+  custom Solid SPA (Vite, SolidStart, etc.) — wiring `configureZitadel`
+  and the `<ZitadelLogin>` / `<ZitadelLogout>` / `<ZitadelSession>`
+  components by hand rather than scaffolding from scratch.
+---
+
+# @zitadel/sdk-solid
+
+Solid components that render the Zitadel auth UI inside a client-side SPA.
+The package wraps the framework-agnostic `<zitadel-*>` web components as
+real Solid components, so login, logout, and the signed-in session card are
+JSX you drop into your routes.
+
+## When to use
+
+- **Fresh project:** prefer the CLI. `npx @zitadel/cli@latest setup --framework solid`
+  scaffolds a wired Solid app (and the dev proxy) for you — see the
+  `zitadel-cli` skill. Don't hand-assemble what the CLI generates.
+- **This skill:** an app that already exists, or a custom integration the
+  scaffold doesn't cover — adding auth to a Solid app you already have,
+  moving the components into your own routes, or wiring the config yourself.
+
+## Install
+
+`solid-js >= 1.6` is a peer dependency, and the published types need
+TypeScript >= 5.0.
+
+```sh
+npm install @zitadel/sdk-solid@latest
+```
+
+## Integrate
+
+Configure once, then render the components. `configureZitadel` returns a
+project handle you pass to each component.
+
+```tsx
+import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-solid';
+
+const project = configureZitadel({
+  projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+  proxyPath: '/__nextgen',
+});
+
+export default function LoginPage() {
+  return <ZitadelLogin project={project} purpose="login" postSignInUrl="/" />;
+}
+```
+
+Logout and the signed-in session card take the same `project` handle:
+
+```tsx
+import { ZitadelLogout, ZitadelSession } from '@zitadel/sdk-solid';
+
+<ZitadelLogout project={project} postSignOutUrl="/login" />;
+<ZitadelSession project={project} />;
+```
+
+`purpose` selects the flow (`"login"`, etc.); `postSignInUrl` /
+`postSignOutUrl` are where the widget navigates after the flow completes.
+The widget's events reach you as the callbacks listed under Widget props and
+events.
+
+**Same-origin proxy.** The widgets call `${proxyPath}/…` same-origin
+(default `/__nextgen`). For local development the CLI dev proxy covers this;
+you can also skip the proxy and point `proxyPath` straight at the backend
+cross-origin, e.g. `proxyPath: "http://localhost:8080"` (the `zitadel start`
+local runtime default port).
+
+## 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
+
+Treat the installed package as authoritative over anything here — this skill
+and the package version move independently.
+
+- `node_modules/@zitadel/sdk-solid/README.md` — the shipped usage doc.
+- `node_modules/@zitadel/sdk-solid/dist/index.d.ts` and the re-exported
+  `@zitadel/sdk-core/types` — the real prop names, component props
+  (`ZitadelLoginProps`, `ZitadelLogoutProps`, `ZitadelSessionProps`), and
+  `configureZitadel`'s config shape. Read the types before wiring a prop you
+  are unsure of rather than assuming its name.
+
+Exported surface (discover-first, confirm against the types above):
+`configureZitadel`, `getApi`, `getZitadelConfig`, the `ZitadelLogin` /
+`ZitadelLogout` / `ZitadelSession` components, `businessLocales`, and the
+`ZitadelConfig` / `ZitadelProject` types.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration, or 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.
+- **Production SPA deployment is not yet supported.** The same-origin proxy
+  path must come from your hosting platform, and the CLI can't scaffold those
+  configs yet, so a production SPA build has no proxy to talk to. See
+  ADR 036 and zitadel/nextgen#560. The CLI dev proxy covers local
+  development only.
+- **TypeScript < 5.0 won't type-check.** The published `.d.ts` re-exports
+  with `export type *`, introduced in TS 5.0.
+- **`solid-js` is a peer dependency** (`>= 1.6`) — install it in the host
+  app; the package does not bundle it.

package/dist/skills/zitadel-sdk-solid-start/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: zitadel-sdk-solid-start
+description: >-
+  Integrate Zitadel authentication into an existing or custom SolidStart app
+  with @zitadel/sdk-solid-start. Use when the user wants login, logout, session
+  handling, or protected routes in a SolidStart 2 app and is wiring the SDK by
+  hand rather than letting the CLI scaffold a fresh project — registering the
+  middleware, reading auth state in a server function, or rendering the
+  `ZitadelLogin` / `ZitadelSession` widgets.
+---
+
+# @zitadel/sdk-solid-start
+
+SolidStart middleware and helpers that add Zitadel (Nextgen) auth to a
+SolidStart app. The middleware proxies auth traffic same-origin under
+`/__nextgen`, verifies the session JWT via JWKS on the server, writes the result
+to `event.locals.nextgenAuth`, and redirects unauthenticated requests on
+protected routes. The package is server-only; the widgets come from
+`@zitadel/sdk-solid`.
+
+## When to use
+
+The `zitadel` CLI (`zitadel setup --framework solid-start`) scaffolds the
+middleware, its `vite.config.ts` registration, login/register/profile routes,
+and `.env.local` into a fresh or detected SolidStart project — prefer it for
+greenfield work. It refuses a SolidStart 1 app. Reach for **this skill** when you
+are adding auth to an **existing or custom** SolidStart app by hand, or
+adjusting a scaffolded wiring.
+
+## Install
+
+```bash
+pnpm add @zitadel/sdk-solid-start@latest
+# the login/logout/session widgets are a separate package:
+pnpm add @zitadel/sdk-solid@latest
+```
+
+Peer deps: `@solidjs/start ^2.0.0`, `solid-js ^1.8.0`.
+
+## Integrate
+
+**1. Middleware.** Create `src/middleware.ts`, wrapped in SolidStart's
+`createMiddleware`, and register it with the `solidStart()` Vite plugin:
+
+```ts
+// src/middleware.ts
+import { createMiddleware } from '@solidjs/start/middleware';
+import { createNextgenMiddleware } from '@zitadel/sdk-solid-start/server';
+
+export default createMiddleware(
+  createNextgenMiddleware({
+    protectedRoutes: ['/admin', '/dashboard*'], // trailing * matches sub-paths
+    loginPath: '/login',
+  }),
+);
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { solidStart } from '@solidjs/start/config';
+import { nitro } from 'nitro/vite';
+
+export default defineConfig({
+  plugins: [solidStart({ middleware: './src/middleware.ts' }), nitro()],
+});
+```
+
+`url` and `projectSecret` default to `ZITADEL_URL` and `ZITADEL_PROJECT_SECRET`
+from the server environment; pass them only to override. Sessions count only in
+the app's own project: `projectId`, else `ZITADEL_PROJECT_ID`, else
+`VITE_ZITADEL_PROJECT_ID`. With none set, nobody is signed in. To compose with your own
+handlers, spread the config's `onRequest` into your own `createMiddleware` call.
+
+**2. Read auth server-side** with `getAuth(getRequestEvent()!)` inside a
+`'use server'` function:
+
+```ts
+import { getRequestEvent } from 'solid-js/web';
+import { getAuth } from '@zitadel/sdk-solid-start/server';
+
+export function requireUser() {
+  'use server';
+  const auth = getAuth(getRequestEvent()!);
+  if (!auth.isAuthenticated) throw new Error('Unauthorized');
+  return auth.session.userId;
+}
+```
+
+`protectedRoutes` only guards full page loads. To keep a route from rendering at
+all without a session, check the session in a `query` that `throw redirect('/login')`
+and call it from the route's `preload` — it runs on the server for client-side
+navigation too.
+
+**3. Render the widgets** from `@zitadel/sdk-solid`, loaded with SolidStart's
+`clientOnly` so they are created in the browser and the package stays out of the
+server render:
+
+```tsx
+import { clientOnly } from '@solidjs/start';
+
+const ZitadelLogin = clientOnly(() =>
+  import('@zitadel/sdk-solid').then((m) => ({ default: m.ZitadelLogin })),
+);
+
+export default function Login() {
+  return (
+    <ZitadelLogin
+      projectId={import.meta.env.VITE_ZITADEL_PROJECT_ID}
+      proxyPath="/__nextgen"
+      purpose="login"
+      postSignInUrl="/admin"
+    />
+  );
+}
+```
+
+`ZitadelSession` (with `postSignOutUrl="/login"`) and `ZitadelLogout` load the
+same way.
+
+## Widget props and events
+
+This SDK is server-only. The widgets come from `@zitadel/sdk-solid`, so read its skill for the widget props and events.
+
+## Read these, don't guess
+
+The package README at `node_modules/@zitadel/sdk-solid-start/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 callbacks, read
+`node_modules/@zitadel/sdk-solid/README.md` and its types. Check exact option
+names and defaults against the installed version rather than assuming.
+
+## Gotchas
+
+- **Wrap the config in `createMiddleware`.** SolidStart 2 registers the default
+  export as an array of h3 middleware; exporting the bare
+  `createNextgenMiddleware(...)` object registers nothing and `/__nextgen/*`
+  404s.
+- **Pass `projectId` / `proxyPath` as props, not a `configureZitadel` handle.**
+  Building the handle imports `@zitadel/sdk-solid` at module scope, outside the
+  `clientOnly` boundary.
+- **`@zitadel/sdk-solid-start` renders no widgets.** They come from
+  `@zitadel/sdk-solid`, which registers custom elements on import — never import
+  it at module scope in a server-rendered file.
+- **Client-side navigation skips the middleware.** Without a preloaded server
+  query, only the `ZitadelSession` card sends a signed-out visitor away.

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

@@ -0,0 +1,137 @@
+---
+name: zitadel-sdk-svelte
+description: >-
+  Integrate Zitadel authentication into an existing Svelte or SvelteKit app
+  with the @zitadel/sdk-svelte components. Use when the user wants to add login,
+  logout, or a signed-in session card to a Svelte 5 / SvelteKit (or Vite SPA)
+  project by hand, wire the auth widgets to a backend, or debug the proxy and
+  post sign-in/out redirects.
+---
+
+# @zitadel/sdk-svelte
+
+`@zitadel/sdk-svelte` ships Svelte 5 components that render the Zitadel auth UI
+(`<ZitadelLogin>`, `<ZitadelLogout>`, `<ZitadelSession>`) for client-side SPAs.
+The components wrap the `@zitadel/components` custom elements and talk to a
+Zitadel backend over a same-origin proxy path.
+
+## When to use
+
+Use this skill for an **existing or custom** Svelte / SvelteKit / Vite app where
+you are adding the auth widgets by hand.
+
+If the user is starting fresh, prefer the `zitadel` CLI instead — it scaffolds a
+working Svelte app and wires the dev proxy for you:
+
+```sh
+npx @zitadel/cli@latest setup --framework svelte --non-interactive --json
+```
+
+## Install
+
+```sh
+npm install @zitadel/sdk-svelte@latest
+```
+
+Peer dependencies: `svelte ^5.0.0`. Requires TypeScript ≥ 5.0 (the published types use `export type *`).
+
+## Integrate
+
+The widgets are **browser** components. In SvelteKit, mount them in a
+`+page.svelte` (they render client-side). The minimal pattern, from the README:
+
+```svelte
+<script lang="ts">
+  import { ZitadelLogin, ZitadelLogout, configureZitadel } from '@zitadel/sdk-svelte';
+
+  const project = configureZitadel({
+    projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+    proxyPath: '/__nextgen',
+  });
+</script>
+
+<ZitadelLogin {project} purpose="login" postSignInUrl="/" />
+<ZitadelLogout {project} postSignOutUrl="/login" />
+```
+
+- **Configure once** with `configureZitadel({ projectId, proxyPath })` and pass
+  the returned `project` to each component.
+- **Proxy / same-origin.** The widgets call `${proxyPath}/…` same-origin
+  (default `/__nextgen`). For local development you can skip the proxy and point
+  `proxyPath` straight at the backend (cross-origin), e.g.
+  `proxyPath: "http://localhost:8080"` (the `zitadel start` default port).
+- **Post URLs.** `postSignInUrl` (on `ZitadelLogin`) and `postSignOutUrl` (on
+  `ZitadelLogout`) are where the browser lands after each flow.
+- **Session card.** `<ZitadelSession {project} />` renders the signed-in user.
+- **Callbacks** are optional props; see 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` |
+
+```svelte
+<ZitadelLogin {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
+
+The installed package is authoritative — it and this skill version independently,
+so discover against what is installed rather than trusting anything hardcoded
+here:
+
+- `node_modules/@zitadel/sdk-svelte/README.md` — the shipped usage doc.
+- `node_modules/@zitadel/sdk-svelte/dist/index.d.ts` and the component prop
+  types (`ZitadelLoginProps`, `ZitadelLogoutProps`, re-exported from
+  `@zitadel/sdk-core/types`) — the exact props, their names, and which are
+  optional. Read the types before passing a prop you are unsure of.
+
+The public exports are `ZitadelLogin`, `ZitadelLogout`, `ZitadelSession`,
+`configureZitadel`, `getApi`, `getZitadelConfig`, `businessLocales`, plus the
+`ZitadelConfig` / `ZitadelProject` types.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration, or 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.
+- **Production SPA deployment is not yet supported.** The same-origin proxy path
+  must come from your hosting platform, and the CLI cannot scaffold those configs
+  yet (see ADR 036 and zitadel/nextgen#560). The CLI dev proxy covers local
+  development only.
+- **`proxyPath` must reach the backend.** A same-origin path needs a proxy in
+  front of your app; without one, point `proxyPath` at the backend origin
+  directly (dev only, cross-origin).
+- **Browser web components.** The widgets only start in the browser. A SvelteKit
+  server render emits a bare element, so follow the server-rendering gotcha
+  above: string `projectId` and `proxyPath` may be server-rendered.

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

@@ -0,0 +1,147 @@
+---
+name: zitadel-sdk-sveltekit
+description: >-
+  Integrate Zitadel authentication into an existing or custom SvelteKit app with
+  @zitadel/sdk-sveltekit. Use when the user wants login, logout, session
+  handling, or protected routes in a SvelteKit 3 app and is wiring the SDK
+  by hand rather than letting the CLI scaffold a fresh project — adding the
+  `handle` hook, reading auth state in a load function, or rendering the
+  `ZitadelLogin` / `ZitadelSession` widgets.
+---
+
+# @zitadel/sdk-sveltekit
+
+A SvelteKit `handle` hook and helpers that add Zitadel (Nextgen) auth to a
+SvelteKit app. The hook proxies auth traffic same-origin under `/__nextgen`,
+verifies the session JWT via JWKS on the server, writes the result to
+`event.locals.nextgenAuth`, and redirects unauthenticated requests on protected
+routes. The package is server-only; the widgets come from `@zitadel/sdk-svelte`.
+
+## When to use
+
+The `zitadel` CLI (`zitadel setup --framework sveltekit`) scaffolds the hook,
+login/register/profile routes, `src/env.ts` and `.env.local` into a fresh or detected
+SvelteKit project — prefer it for greenfield work. Reach for **this skill** when
+you are adding auth to an **existing or custom** SvelteKit app by hand, or
+adjusting a scaffolded wiring.
+
+## Install
+
+```bash
+pnpm add @zitadel/sdk-sveltekit@latest
+# the login/logout/session widgets are a separate package:
+pnpm add @zitadel/sdk-svelte@latest
+```
+
+Peer deps: `@sveltejs/kit ^3.0.0`, `svelte ^5.0.0`.
+
+## Integrate
+
+**1. Server hook.** Declare the settings in `src/env.ts` (SvelteKit 3), so
+SvelteKit serves them from the server-only `$app/env/private` — from
+`.env.local` in dev, from the platform in production. An app that already
+has `src/env.ts` adds the three entries to its own `defineEnvVars` call:
+
+```ts
+import { defineEnvVars } from '@sveltejs/kit/env';
+
+export const variables = defineEnvVars({
+  ZITADEL_URL: {},
+  ZITADEL_PROJECT_SECRET: {},
+  ZITADEL_PROJECT_ID: {},
+});
+```
+
+Then create or extend `src/hooks.server.ts`:
+
+```ts
+import { ZITADEL_PROJECT_ID, ZITADEL_PROJECT_SECRET, ZITADEL_URL } from '$app/env/private';
+import { createNextgenHandle } from '@zitadel/sdk-sveltekit/server';
+
+export const handle = createNextgenHandle({
+  url: ZITADEL_URL,
+  projectSecret: ZITADEL_PROJECT_SECRET,
+  projectId: ZITADEL_PROJECT_ID,
+  protectedRoutes: ['/admin', '/dashboard*'], // trailing * matches sub-paths
+  loginPath: '/login',
+});
+```
+
+Do not read them from `process.env`: SvelteKit never puts `.env` files there.
+Compose with other hooks via
+`sequence()` from `@sveltejs/kit/hooks`. Sessions count only in the app's own
+project: `projectId`, else `ZITADEL_PROJECT_ID`, else
+`VITE_ZITADEL_PROJECT_ID`. With none set, nobody is signed in.
+
+**2. Read auth server-side** with `getAuth(event)` in a load function or
+endpoint, and forward only client-safe fields to the page — never the raw token:
+
+```ts
+import { redirect } from '@sveltejs/kit';
+import { getAuth } from '@zitadel/sdk-sveltekit/server';
+
+export const load = (event) => {
+  const auth = getAuth(event);
+  if (!auth.isAuthenticated) throw redirect(302, '/login');
+  return { identifier: auth.session.identifier };
+};
+```
+
+`protectedRoutes` only guards full page loads. To keep a page from rendering at
+all without a session, guard it in a `+page.server.ts` load like the one above —
+SvelteKit runs that load on the server for client-side navigation too. A
+universal `+page.ts` load does not work: it runs in the browser, where `locals`
+are not available.
+
+**3. Render the widgets** from `@zitadel/sdk-svelte`, mounted on the client only
+(set a flag in `onMount` and wrap the widget in `{#if mounted}`):
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-svelte';
+
+  const project = configureZitadel({
+    projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+    proxyPath: '/__nextgen',
+  });
+
+  let mounted = $state(false);
+  onMount(() => (mounted = true));
+</script>
+
+{#if mounted}
+  <ZitadelLogin {project} purpose="login" postSignInUrl="/admin" />
+{/if}
+```
+
+`<ZitadelSession {project} postSignOutUrl="/login" />` renders the signed-in
+card with sign-out, and `<ZitadelLogout>` a sign-out control on its own; mount
+them the same way.
+
+## Widget props and events
+
+This SDK is server-only. The widgets come from `@zitadel/sdk-svelte`, so read its skill for the widget props and events.
+
+## Read these, don't guess
+
+The package README at `node_modules/@zitadel/sdk-sveltekit/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 callbacks, read
+`node_modules/@zitadel/sdk-svelte/README.md` and its types. Check exact option
+names and defaults against the installed version rather than assuming.
+
+## Gotchas
+
+- **`@zitadel/sdk-sveltekit` renders no widgets.** Importing `ZitadelLogin` from
+  it fails; it comes from `@zitadel/sdk-svelte`.
+- **Mount the widgets client-side only.** Their config is set as element
+  properties, which server-rendered markup cannot carry; use `onMount`, not the
+  deprecated `$app/environment` (SvelteKit 3).
+- **Keep `App.Locals` declared.** The package merges `nextgenAuth` into it, so
+  `src/app.d.ts` must keep the `App` namespace with a `Locals` interface.
+- **Client-side navigation skips the hook.** Without a `+page.server.ts` guard,
+  only the `ZitadelSession` card sends a signed-out visitor away.