Upgrade your storefront kit

If your site runs from your own code, because you got the code with storefront init or you host the site yourself, that code uses two EcomWeb packages, @ecomweb/storefront-kit and @ecomweb/sdk. This guide shows how to see which version you use, move to the latest one and put your site live again.

If your store only uses a ready-made theme and you have no code of your own, you don't need to do anything. EcomWeb updates these packages for ready-made themes.

Why upgrades matter

These two packages are the code that connects your site to EcomWeb: products, the cart, checkout and customer accounts. Each new version fixes bugs and adds features. Some versions are security fixes, which close a bug that someone could use against your site.

Your code lives on your computer or in your own repository, so EcomWeb cannot change it for you. You upgrade and deploy it yourself. The latest version always works with EcomWeb.

See which version you use

In the dashboard:

1. In the sidebar, click Online Store.
2. Look for [the notice at the top of the page]. It only shows when there is a newer version than the one your site runs, and it gives your version, the latest version and the command to run.

A red notice means a security fix, so upgrade now. Amber means your version is too old and EcomWeb no longer supports it. A lighter notice only says a new version is out. No notice means your site runs the latest version, or EcomWeb has not seen your site call it in the last 30 days.

On your computer, in your project folder:

# Show your version and the command it would run, without changing anything
$ ecomweb storefront upgrade --dry-run

When you run an ecomweb command in your project folder, the CLI also prints a one-line reminder when a new version is out, at most once a day. pnpm build also prints a warning when your version is behind.

Upgrade the two packages

1. Update the EcomWeb CLI to the latest version, so it has the upgrade command.
2. Open a terminal in your project folder.
3. Run the upgrade command below.

# Update the CLI
$ npm install -g @ecomweb/cli
# Move @ecomweb/sdk and @ecomweb/storefront-kit to the latest version
$ ecomweb storefront upgrade

The command finds out from your project’s lockfile whether it uses pnpm, npm or yarn, then installs the latest version of both packages. At the end it prints a link to the changelog and reminds you to build and deploy.

If you haven’t installed the CLI yet, see Install and sign in to the EcomWeb CLI.

Read the changelog

Each new version has release notes on the ecomweb-storefront-sdk releases page. They say what the version fixes, what it adds and whether you need to change anything in your code.

1. Open the releases page.
2. Read every version after the one you use, up to the latest.
3. Follow the steps listed for any part of the code you have changed.

Build and deploy again

1. Run pnpm dev and open a few key pages to check that everything still works: the home page, a product and the cart.
2. Run pnpm build to make sure the code builds.
3. Run ecomweb deploy in your project folder.
4. Open the preview link the terminal prints and check again.
5. Publish as you would after any other deploy.

$ pnpm build
$ ecomweb deploy

If your version is below the minimum, ecomweb deploy prints a warning but still deploys.

If you host your site yourself, deploy it the way you always do on your own server. See Connect a self-hosted site.

Understand security emails

When a security fix comes out, EcomWeb emails the owners of stores whose site still runs a version older than the fix. The email says what the bug is, which version fixes it and the command to run.

You get one email per fix for each store. The email does not mean your site was attacked. It means your site runs a version with a known bug. Upgrade, build and deploy as above. Once the new version runs, the red notice in the dashboard goes away by itself.

Let GitHub remind you

If your code is on GitHub, Dependabot or Renovate can open a pull request on their own when a new version of the two packages comes out. You only review it, merge it, then build and deploy.

For Dependabot, add a .github/dependabot.yml file to your repository:

$ version: 2
$ updates:
$   - package-ecosystem: npm
$     directory: /
$     schedule:
$       interval: weekly
$     allow:
$       - dependency-name: "@ecomweb/*"

For Renovate, install the Renovate app on your repository. Renovate finds the @ecomweb packages in package.json on its own.

Frequently asked questions