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.
Why you are seeing this
Section titled “Why you are seeing this”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 deployprints a longer warning when you are belowminimum_supportedorsecurity_minimum. SetECOMWEB_NO_UPDATE_CHECKto turn the CLI notice and the deploy check off. - A warning during
next build, fromcheckClientVersionsin yournext.config.mjs. SetECOMWEB_SKIP_VERSION_CHECK=1to 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.
Check your versions
Section titled “Check your versions”Run the CLI in the project folder. A dry run changes nothing and prints what is installed and what is latest.
ecomweb storefront upgrade --dry-runYou 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.
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
Section titled “Upgrade”Upgrade both packages together and to the same version. They are released in lockstep.
- 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, runpnpm add @ecomweb/sdk@<version> @ecomweb/storefront-kit@<version>. - 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.
- Run
pnpm check, thenpnpm build. Fix every type error the build reports. - Deploy. For a store on EcomWeb hosting, run
ecomweb deployand 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.
What changed
Section titled “What changed”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.
0.14.0
Section titled “0.14.0”- Every SDK request sends
X-Ecomweb-Client.createEcomwebSdktakes an optionalclientInfo, and the SDK exportsSDK_VERSION,SDK_CLIENT_TOKEN,CLIENT_HEADER,clientHeaderValue()andwithClientHeader(). - New
checkClientVersions({ phase, apiUrl })in@ecomweb/storefront-kit/config. Ejected storefronts must changenext.config.mjsto 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.
0.13.0 and 0.13.1
Section titled “0.13.0 and 0.13.1”- 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_bindingandconfirmation_bindingin httpOnly cookies.AuthApi.verifyEmail(token, binding?)andconfirmEmailChange(token, binding?)take the binding.CreateOrderRequesthaspromotion_code?. - Breaking in 0.13.0:
orders.lookupGuest()returns the order, ornullwhen nothing matches, and no longer a{ order, found }object.GuestOrderLookupResultis removed. Update code that read.orderor.found. cart.merge()is typedCartApiResponse | { merged: false }.Store.user_idis optional.BlogComment.author_emailis optional.errorCopyhas text forPROMOTION_IDENTITY_REQUIRED. Coming soon previews are more reliable.
0.12.0 and 0.12.1
Section titled “0.12.0 and 0.12.1”- The subdomain redirects to a custom domain only after the domain is verified.
StoreConfighas an optionalverified. - Signing in moves the guest cart into the account instead of losing it. Cart lines keep the order they were added in. A
buildStoreUrlfix stops signed-out shoppers going to//login. - New
useBankTransferDetails,shouldShowBankTransferDetailsandpickBankTransfer.AUTH_ACCOUNT_DISABLEDis a knownAuthErrorCode.errorCopyhas text forPROMOTION_USAGE_LIMIT_REACHEDandBLOG_COMMENTS_DISABLED. StoreSettingshas optionalblog_description,posts_per_pageandallow_comments.- No breaking changes.
0.11.0
Section titled “0.11.0”- Coming soon stores. A store its merchant has not opened shows a coming soon page. Your app owns
app/coming-soon/page.tsx. CallresolveComingSoonStore()and returncomingSoonStoreMetadata(name). Kits below 0.11.0 show a 404 or error page instead. - New exports:
isStoreComingSoonError,comingSoonStoreNameOf,STORE_COMING_SOON_REDIRECT_PATH,resolveComingSoonStoreandreadStorePreviewToken.StorefrontKitProvidertakesstorePreviewTokenandonStorePreviewRenew. - Previews are read-only.
placeOrderand cart writes are refused in a preview. stores.getByDomainandstores.getByIdtake optional request options. No breaking changes.
For how the SDK reports these states, see Errors in the SDK.
Ejected or copied storefronts
Section titled “Ejected or copied storefronts”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:
ecomweb storefront init ../fresh-copyLook 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.
Does an old kit stop working?
Section titled “Does an old kit stop working?”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.
Which version is the latest?
Section titled “Which version is the latest?”Run ecomweb storefront upgrade --dry-run, or read latest from the versions endpoint above.
Can I upgrade only the kit?
Section titled “Can I upgrade only the kit?”Upgrade both together. The kit depends on the SDK and the two are released with the same version.