Align preview bundle releases and naming

Author: fforootd

.changeset/README.md

@@ -22,13 +22,15 @@ corepack pnpm changeset
 
 Pick the affected packages, the bump type (patch / minor / major), and write a one-line summary. A markdown file appears in this directory and gets committed with your PR.
 
-## Alpha prerelease mode
+## Alpha versions, preview channel
 
-The repo is currently in changesets **prerelease mode** with the `alpha` tag (see `.changeset/pre.json`). While in this mode:
+The repo is currently in changesets **prerelease mode** with the `alpha` tag
+(see `.changeset/pre.json`). The `alpha` tag controls the version suffix; the
+public npm channel for community testing is `preview`. While in this mode:
 
 - `changeset version` cuts versions like `0.1.0-alpha.0`, `0.1.0-alpha.1`, …
-- `changeset publish` publishes them under the **`alpha`** npm dist-tag, **not** `latest`. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into prereleases with `@zitadel/cli@alpha`.
-- A package that has never had a stable release is published to `latest` on its first publish (changesets behaviour), then to `alpha` thereafter until it has a stable release.
+- `changeset publish --tag preview` publishes them under the **`preview`** npm dist-tag, **not** `latest`. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into preview bundles with `@zitadel/cli@preview`.
+- The public packages are configured as a fixed MVP preview group, so the Version Packages PR keeps their versions aligned.
 
 To leave alpha and cut a stable `latest` release:
 
@@ -39,7 +41,7 @@ corepack pnpm changeset version   # strips the -alpha suffix
 
 ## Publishing (npm trusted publishing / OIDC)
 
-The [`.github/workflows/release-npm.yml`](../.github/workflows/release-npm.yml) workflow runs the [changesets GitHub Action](https://github.com/changesets/action). Pushing changesets to `main` opens a "Version Packages" PR aggregating all pending changesets; merging that PR bumps versions, updates `CHANGELOG.md` files, and publishes to npm (under the `alpha` dist-tag while in prerelease mode).
+The [`.github/workflows/release-npm.yml`](../.github/workflows/release-npm.yml) workflow runs the [changesets GitHub Action](https://github.com/changesets/action). Pushing changesets to `main` opens a "Version Packages" PR aggregating all pending changesets; merging that PR bumps versions, updates `CHANGELOG.md` files, and publishes to npm (under the `preview` dist-tag while in prerelease mode). Package-level GitHub Releases are disabled; GoReleaser owns the product-level `ZITADEL Preview` releases.
 
 Publishing authenticates with **npm trusted publishing (OIDC)** — there is **no `NPM_TOKEN`** secret. Before the first automated publish, a maintainer must, once per public package:
 

.changeset/config.json

@@ -2,7 +2,19 @@
   "$schema": "https://unpkg.com/@changesets/config@latest/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "zitadel/nextgen" }],
   "commit": false,
-  "fixed": [],
+  "fixed": [
+    [
+      "@zitadel/cli",
+      "@zitadel/api",
+      "@zitadel/components",
+      "@zitadel/sdk-core",
+      "@zitadel/sdk-next",
+      "@zitadel/sdk-nuxt",
+      "@zitadel/sdk-react",
+      "@zitadel/sdk-vue",
+      "@zitadel/sdk-angular"
+    ]
+  ],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

.changeset/preview-bundle-channel.md

@@ -0,0 +1,13 @@
+---
+"@zitadel/cli": patch
+"@zitadel/api": patch
+"@zitadel/components": patch
+"@zitadel/sdk-core": patch
+"@zitadel/sdk-next": patch
+"@zitadel/sdk-nuxt": patch
+"@zitadel/sdk-react": patch
+"@zitadel/sdk-vue": patch
+"@zitadel/sdk-angular": patch
+---
+
+Publish the MVP preview bundle through the `preview` channel and align CLI, SDK, component, and local runtime image naming.

.github/instructions/consumer-journey.instructions.md

@@ -12,10 +12,10 @@ demo-app e2e suite.
 - Produce package artifacts with `corepack pnpm --dir <package> pack` and keep
   tarball verification for required package presence plus unresolved
   `catalog:` or `workspace:` dependency specs.
-- Pack only the six public Zitadel packages. Private support packages such as
-  design tokens must not be uploaded or published to Verdaccio.
+- Pack only the public preview Zitadel packages. Private support packages such
+  as design tokens must not be uploaded or published to Verdaccio.
 - Keep Verdaccio proxying npmjs for third-party dependencies while publishing
-  Zitadel tarballs under both `alpha` and `latest`.
+  Zitadel tarballs under the `preview` dist-tag.
 - Keep generated Next.js apps outside the repo and use `npm` inside the
   generated app to match the documented consumer path.
 - Preserve the CLI setup JSON contract: `--non-interactive --json` must parse

.github/instructions/release-docs.instructions.md

@@ -16,6 +16,9 @@ state of the repo.
 - The release workflow is manual and draft-oriented while the repo is
   pre-release. Do not imply official npm publishing is enabled.
 - npm package changes use changesets; Go server releases use GoReleaser.
+- Public preview docs should use `@zitadel/cli@preview` and
+  `ghcr.io/zitadel/zitadel-preview`; keep `nextgen` only for repo-internal or
+  temporary compatibility alias contexts.
 - Keep licensing text aligned with `LICENSING.md`: AGPL-3.0-only by default,
   MIT exceptions for CLI, SDKs, API contracts, and docs.
 - Docs that mention repo behavior should point to `AGENTS.md`; docs that mention

.github/workflows/ci.yml

@@ -148,7 +148,7 @@ jobs:
           # for ubuntu-latest smoke jobs (see quickstart-smoke).
           IMAGE_ID=""
           IMAGE_REF=""
-          for id in $(docker images ghcr.io/zitadel/nextgen --format '{{.ID}}' | sort -u); do
+          for id in $(docker images ghcr.io/zitadel/zitadel-preview --format '{{.ID}}' | sort -u); do
             arch=$(docker image inspect -f '{{.Architecture}}' "$id")
             ref=$(docker image inspect -f '{{index .RepoTags 0}}' "$id")
             case "$ref" in *snapshot*) ;; *) continue ;; esac
@@ -159,12 +159,12 @@ jobs:
             fi
           done
           if [ -z "$IMAGE_ID" ]; then
-            echo "::error::no linux/amd64 snapshot image found for ghcr.io/zitadel/nextgen"
-            docker images ghcr.io/zitadel/nextgen
+            echo "::error::no linux/amd64 snapshot image found for ghcr.io/zitadel/zitadel-preview"
+            docker images ghcr.io/zitadel/zitadel-preview
             exit 1
           fi
           # Save by a stable local tag: docker save by ID drops repo tags from the tarball.
-          CI_IMAGE="ghcr.io/zitadel/nextgen:ci-snapshot-smoke-amd64"
+          CI_IMAGE="ghcr.io/zitadel/zitadel-preview:ci-snapshot-smoke-amd64"
           docker tag "$IMAGE_ID" "$CI_IMAGE"
           echo "$CI_IMAGE" > dist/nextgen-image.tag
           docker save "$CI_IMAGE" -o dist/nextgen-image.tar
@@ -201,7 +201,7 @@ jobs:
           key: embedded-postgres-${{ runner.os }}-${{ hashFiles('go.sum') }}
       - name: Extract linux/amd64 server binary
         run: |
-          TARBALL="$(find goreleaser-dist -name 'nextgen_*_linux_amd64.tar.gz' | head -1)"
+          TARBALL="$(find goreleaser-dist -name 'zitadel-preview_*_linux_amd64.tar.gz' | head -1)"
           test -n "$TARBALL"
           tar -xzf "$TARBALL" -C .
           test -x ./nextgen
@@ -541,14 +541,14 @@ jobs:
 
       - name: Dry-run npm packs
         run: |
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --dry-run
           done
 
       - name: Create npm package artifacts
         run: |
           mkdir -p "$RUNNER_TEMP/zitadel-npm-packages"
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --pack-destination "$RUNNER_TEMP/zitadel-npm-packages"
           done
           ls -lh "$RUNNER_TEMP/zitadel-npm-packages"

.github/workflows/release-npm.yml

@@ -7,9 +7,9 @@ name: release-npm
 # merging that PR publishes to npm.
 #
 # The repo is in changesets PRERELEASE mode (.changeset/pre.json, tag "alpha"),
-# so versions are cut as X.Y.Z-alpha.N and published under the `alpha` npm
+# so versions are cut as X.Y.Z-alpha.N and published under the `preview` npm
 # dist-tag — `npm install @zitadel/cli` keeps resolving the last stable
-# `latest`; consumers opt into prereleases with `@zitadel/cli@alpha`. Run
+# `latest`; consumers opt into preview bundles with `@zitadel/cli@preview`. Run
 # `pnpm changeset pre exit` to leave alpha and cut a stable `latest` release.
 #
 # Authentication uses npm trusted publishing (OIDC) — there is no NPM_TOKEN.
@@ -88,12 +88,14 @@ jobs:
         run: corepack pnpm nx run-many -t build
 
       - name: Create release PR or publish to npm
+        id: changesets
         uses: changesets/action@v1
         with:
           version: corepack pnpm changeset version
-          publish: corepack pnpm changeset publish
+          publish: corepack pnpm changeset publish --tag preview
           title: "chore: version packages"
           commit: "chore: version packages"
+          createGithubReleases: false
         env:
           # App token (not GITHUB_TOKEN) so the Version Packages PR triggers CI.
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/release.yml

@@ -59,6 +59,10 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
+      - name: Verify preview bundle versions
+        if: ${{ ! inputs.snapshot }}
+        run: node scripts/verify-preview-release.mjs --tag "${{ inputs.ref }}"
+
       - name: Login to GHCR
         if: ${{ ! inputs.snapshot }}
         uses: docker/login-action@v4

.goreleaser.yaml

@@ -32,7 +32,7 @@ archives:
     format_overrides:
       - goos: windows
         formats: [zip]
-    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}'
+    name_template: 'zitadel-preview_{{ .Version }}_{{ .Os }}_{{ .Arch }}'
     files:
       - LICENSE
       - README.md
@@ -41,11 +41,14 @@ dockers_v2:
   - id: nextgen
     ids: [nextgen]
     images:
+      - 'ghcr.io/zitadel/zitadel-preview'
+      # Temporary compatibility alias while the repository is still named nextgen.
       - 'ghcr.io/zitadel/nextgen'
     tags:
       - '{{ .Version }}'
-      # Skip `latest` for snapshots so they don't clobber the published tag.
-      - '{{ if not .IsSnapshot }}latest{{ end }}'
+      # The public moving prerelease channel is `preview`; never publish
+      # prerelease artifacts to Docker `latest`.
+      - '{{ if not .IsSnapshot }}preview{{ end }}'
     platforms:
       - linux/amd64
       - linux/arm64
@@ -69,4 +72,5 @@ changelog:
   use: github
 
 release:
+  name_template: 'ZITADEL Preview {{ .Version }}'
   draft: true

AGENTS.md

@@ -49,8 +49,9 @@ Secrets").
   Playwright project. It installs local package tarballs through a temporary
   registry and verifies CLI setup plus real registration/login flows.
 - `packages/components/` contains shared Lit components.
-- `packages/sdk-core/`, `packages/sdk-next/`, and `packages/sdk-nuxt/` contain
-  public TypeScript SDKs.
+- `packages/sdk-core/`, `packages/sdk-next/`, `packages/sdk-nuxt/`,
+  `packages/sdk-react/`, `packages/sdk-vue/`, and `packages/sdk-angular/`
+  contain public TypeScript SDKs.
 - `packages/api-mock/` contains the in-process MSW handlers and standalone
   mock auth server used by demos and e2e tests.
 - `packages/lint/` contains the local Nx plugin that infers Oxlint targets.
@@ -74,12 +75,12 @@ Secrets").
 
 | I want to...                      | Run                                                            |
 | --------------------------------- | -------------------------------------------------------------- |
-| Check local runtime prerequisites | `npx @zitadel/cli@alpha doctor`                                |
-| Start local Zitadel               | `npx @zitadel/cli@alpha start`                                 |
-| Add auth to Next.js               | `npx @zitadel/cli@alpha setup --framework next --server local` |
-| Check generated app files         | `npx @zitadel/cli@alpha doctor`                                |
-| Stop local Zitadel, keeping data  | `npx @zitadel/cli@alpha stop`                                  |
-| Delete local Zitadel data         | `npx @zitadel/cli@alpha reset --force`                         |
+| Check local runtime prerequisites | `npx @zitadel/cli@preview doctor`                              |
+| Start local Zitadel               | `npx @zitadel/cli@preview start`                               |
+| Add auth to Next.js               | `npx @zitadel/cli@preview setup --framework next --server local` |
+| Check generated app files         | `npx @zitadel/cli@preview doctor`                              |
+| Stop local Zitadel, keeping data  | `npx @zitadel/cli@preview stop`                                |
+| Delete local Zitadel data         | `npx @zitadel/cli@preview reset --force`                       |
 
 `corepack pnpm run server` is a repository contributor command that runs the Go
 server from source. `zitadel start` is a published product CLI command that
@@ -213,7 +214,8 @@ For customer-local runtime workflows, agents should prefer
 - User-visible changes to a public npm package need a changeset. The public
   packages are `@zitadel/cli` (`apps/cli/`), `@zitadel/api`,
   `@zitadel/components`, `@zitadel/sdk-core`, `@zitadel/sdk-next`, and
-  `@zitadel/sdk-nuxt`. CI fails a PR that touches them without one
+  `@zitadel/sdk-nuxt`, `@zitadel/sdk-react`, `@zitadel/sdk-vue`, and
+  `@zitadel/sdk-angular`. CI fails a PR that touches them without one
   (`changeset-check` in `.github/workflows/ci.yml`).
 - Add a changeset by writing the file directly — do not depend on the
   interactive `pnpm changeset` prompt. Create `.changeset/<short-slug>.md`:
@@ -227,9 +229,9 @@ For customer-local runtime workflows, agents should prefer
   ```
 
   List only public package names; pick `patch` (fixes), `minor` (features), or
-  `major` (breaking). The repo is in `alpha` prerelease mode
-  (`.changeset/pre.json`), so versions cut as `X.Y.Z-alpha.N` automatically — no
-  extra action needed.
+  `major` (breaking). The repo is in `alpha` prerelease mode for version
+  suffixes (`.changeset/pre.json`), while npm publishing uses the `preview`
+  dist-tag for the community-testable bundle.
 
 - For changes that release nothing (docs, tests, CI, chores), add an empty
   changeset: `corepack pnpm changeset --empty`.