Distribution channels ​
The @shopware/* packages are published through three channels. Each serves a different need: shipping to production, testing what is already merged to main, or trying the code from a single open pull request.
Stable and canary cover all published packages:
@shopware/api-client@shopware/api-gen@shopware/cms-base-layer@shopware/composables@shopware/helpers@shopware/nuxt-module@shopware/unocss-design-tokens-layer
TL;DR
Use Stable for production and everyday app development. Use Canary to test changes already merged to main but not yet released. Use PR previews to try the exact code from a single open pull request.
Summary ​
| Channel | Source | Stability | When to use |
|---|---|---|---|
| Stable | npm tag latest | Stable, semver | Production and normal app development. The default. |
| Canary | npm tag canary | Unstable, no semver | Test changes merged to main but not yet released. |
| PR preview | pkg-pr-new (not on npm) | Ephemeral, per-PR | Try the code from one specific open pull request. |
Stable ​
Normal production releases, managed by Changesets and published to npm under the default latest dist-tag.
Contributors add a changeset in their PR (pnpm changeset). The Release GitHub workflow (.github/workflows/release.yml) aggregates pending changesets into a chore: next version release PR. Merging that PR runs changeset publish, which publishes to npm under latest and creates the matching git tags and GitHub releases.
# Latest stable
npm i @shopware/api-client
# Pin an exact version
npm i @shopware/api-client@1.5.0When to use
Production and any normal app development. This is the default and the only channel with semver guarantees - if you are unsure, use this one.
Canary ​
Snapshot pre-releases published to npm under the canary dist-tag automatically on every push to main by the publish-canary job, except for the release commit chore: next version release. Only packages with pending (unreleased) changesets get a fresh canary snapshot.
The job runs:
pnpm run version --snapshot canary
pnpm changeset publish --no-git-tag --tag canaryVersions use the format 0.0.0-canary-<UTC-timestamp>, for example 0.0.0-canary-20260629144551.
# Newest canary snapshot
npm i @shopware/api-client@canary
# Pin an exact snapshot for reproducibility
npm i @shopware/api-client@0.0.0-canary-20260629144551Because the canary tag always points at the newest snapshot, pin the exact snapshot version when you need a reproducible install.
When to use
To verify a fix or feature early, or for integration testing of changes that are merged to main but not yet in a stable release.
Not for production
Canary snapshots are unstable, change frequently, and carry no semver guarantees.
PR preview ​
Per-pull-request preview builds powered by pkg-pr-new. These builds are not published to the npm registry; they are served directly from pkg.pr.new.
The package-previews workflow (.github/workflows/package-previews.yml) triggers on a pull request labeled event, only when the label is publish-pkg-preview. It builds the packages and runs:
npx pkg-pr-new publish ./packages/api-client ./packages/api-gen ./packages/cms-base-layer ./packages/composables ./packages/helpers ./packages/nuxt-moduleThe pkg-pr-new bot then comments the install commands on the PR. Install directly from the preview URL:
# By PR number
npm i https://pkg.pr.new/shopware/frontends/@shopware/api-client@1349
# A commit SHA also works in place of the PR number
npm i https://pkg.pr.new/shopware/frontends/@shopware/api-client@<commit-sha>Opt-in
Previews are opt-in: a maintainer adds the publish-pkg-preview label to the PR to trigger a build.
When to use
To try the exact code from a specific open pull request before it is merged - for review, reproducing a bug fix, or validating against your app. Previews are ephemeral and tied to that PR.
See the quick start guide for setting up a project and Best practices: Deployment for production guidance.
