Skip to content

Upgrade the storefront kit

This guide shows how to move a storefront to a newer @ecomweb/sdk and @ecomweb/storefront-kit. You need a storefront project that uses both packages, with a terminal in its folder. Stores that EcomWeb hosts with a ready-made theme need nothing, because EcomWeb keeps that build current. This guide is for storefronts you built, ejected or host yourself.

Every request the SDK sends carries an X-Ecomweb-Client header with the kit and SDK versions. The platform records the latest versions it has seen for your store, and compares them with two numbers for each package.

Number What it means
minimum_supported Below this version the dashboard and the CLI warn that your kit is no longer supported
security_minimum Below this version your kit has a known security issue. The dashboard shows a red banner and the store owner gets an email

You see the result in three places:

  • A banner in the store’s dashboard, titled Security update for your storefront kit, Your storefront kit is no longer supported or A storefront kit update is available. It shows the version you run, the latest version, the advisories the update fixes and the command to run.
  • A line in the CLI after any command run inside a storefront project, at most one check a day. ecomweb deploy prints a longer warning when you are below minimum_supported or security_minimum. Set ECOMWEB_NO_UPDATE_CHECK to turn the CLI notice and the deploy check off.
  • A warning during next build, from checkClientVersions in your next.config.mjs. Set ECOMWEB_SKIP_VERSION_CHECK=1 to turn it off. It waits 2 seconds at most and never fails the build.

Nothing refuses an old client. Your storefront keeps working and the deploy still goes ahead. Some security fixes change what the API expects from clients, so an old kit can still fail at one step, such as email verification, as the release notes below say. The platform also emails the store owner once each time security_minimum rises above a version the store was seen running in the last 30 days.

Run the CLI in the project folder. A dry run changes nothing and prints what is installed and what is latest.

Terminal window
ecomweb storefront upgrade --dry-run

You can also read the versions in package.json or node_modules/@ecomweb/storefront-kit/package.json. The platform’s current numbers are public. They need no key.

Terminal window
curl "https://apibase.ecomweb.app/api/v1/public/storefront-clients/versions"

The answer has packages with latest, minimum_supported and security_minimum for @ecomweb/storefront-kit and @ecomweb/sdk, then advisories and upgrade_guide_url. latest comes from the npm registry and is cached for an hour.

Upgrade both packages together and to the same version. They are released in lockstep.

  1. Run ecomweb storefront upgrade. It finds your package manager from the lockfile and adds the latest version of both packages. To do it by hand, run pnpm add @ecomweb/sdk@<version> @ecomweb/storefront-kit@<version>.
  2. Read What changed for every release between your version and the new one. Before 1.0, a minor release can break, so each of them matters.
  3. Run pnpm check, then pnpm build. Fix every type error the build reports.
  4. Deploy. For a store on EcomWeb hosting, run ecomweb deploy and wait for the build. See Hosting.

A project made from the Claude Code plugin has the /ecomweb:update command. It refreshes the project’s ecomweb skill, runs pnpm update on both packages, runs pnpm check and reports what changed. Because pnpm update keeps to your range, run ecomweb storefront upgrade first when you need a newer minor release. See Build your store with Claude Code.

The notes cover every minor release from 0.11.0 to 0.14.0, with the patch releases between them. The full changelogs are in the release notes.

  • Every SDK request sends X-Ecomweb-Client. createEcomwebSdk takes an optional clientInfo, and the SDK exports SDK_VERSION, SDK_CLIENT_TOKEN, CLIENT_HEADER, clientHeaderValue() and withClientHeader().
  • New checkClientVersions({ phase, apiUrl }) in @ecomweb/storefront-kit/config. Ejected storefronts must change next.config.mjs to export an async function that calls it to get the build warning. New projects already do:
import { checkClientVersions } from "@ecomweb/storefront-kit/config";
export default async function config(phase) {
await checkClientVersions({ phase, apiUrl: process.env.ECOMWEB_API_URL });
return nextConfig;
}
  • No breaking changes.
  • Security, fixed in 0.13.1, advisory ECW-2026-11-01 (high). Email verification and email change links are bound to the browser that asked for them, and checkout sends the promotion code with the promotion. Kits below 0.13.1 fail email verification, email change and discount codes at checkout against the current API. Upgrade to 0.13.1 or later.
  • The auth route keeps the verification_binding and confirmation_binding in httpOnly cookies. AuthApi.verifyEmail(token, binding?) and confirmEmailChange(token, binding?) take the binding. CreateOrderRequest has promotion_code?.
  • Breaking in 0.13.0: orders.lookupGuest() returns the order, or null when nothing matches, and no longer a { order, found } object. GuestOrderLookupResult is removed. Update code that read .order or .found.
  • cart.merge() is typed CartApiResponse | { merged: false }. Store.user_id is optional. BlogComment.author_email is optional.
  • errorCopy has text for PROMOTION_IDENTITY_REQUIRED. Coming soon previews are more reliable.
  • The subdomain redirects to a custom domain only after the domain is verified. StoreConfig has an optional verified.
  • Signing in moves the guest cart into the account instead of losing it. Cart lines keep the order they were added in. A buildStoreUrl fix stops signed-out shoppers going to //login.
  • New useBankTransferDetails, shouldShowBankTransferDetails and pickBankTransfer. AUTH_ACCOUNT_DISABLED is a known AuthErrorCode. errorCopy has text for PROMOTION_USAGE_LIMIT_REACHED and BLOG_COMMENTS_DISABLED.
  • StoreSettings has optional blog_description, posts_per_page and allow_comments.
  • No breaking changes.
  • Coming soon stores. A store its merchant has not opened shows a coming soon page. Your app owns app/coming-soon/page.tsx. Call resolveComingSoonStore() and return comingSoonStoreMetadata(name). Kits below 0.11.0 show a 404 or error page instead.
  • New exports: isStoreComingSoonError, comingSoonStoreNameOf, STORE_COMING_SOON_REDIRECT_PATH, resolveComingSoonStore and readStorePreviewToken. StorefrontKitProvider takes storePreviewToken and onStorePreviewRenew.
  • Previews are read-only. placeOrder and cart writes are refused in a preview.
  • stores.getByDomain and stores.getById take optional request options. No breaking changes.

For how the SDK reports these states, see Errors in the SDK.

A storefront that you ejected or copied from a template has its own copy of the template’s code, such as pages, components and next.config.mjs. Upgrading the packages does not change that code. When a release says new projects already have a change, port it by hand. Compare your files with a freshly generated project:

Terminal window
ecomweb storefront init ../fresh-copy

Look at next.config.mjs, proxy.ts, the two route handlers and your layout. Then walk the notes above and apply each item that touches code you own, such as the next.config.mjs change in 0.14.0 and the coming soon page in 0.11.0. Run pnpm check and pnpm build after each batch so a type error points at one change.

No. Nothing refuses a request because the kit is old. Some API changes still break old clients at one step. The 0.13.1 advisory is an example.

Run ecomweb storefront upgrade --dry-run, or read latest from the versions endpoint above.

Upgrade both together. The kit depends on the SDK and the two are released with the same version.