Skip to content

Edit a theme's code and deploy it

You download a theme’s code, edit it with the tools you already use, and deploy it again. EcomWeb builds the code and runs it on your store’s domain. Every deploy is a new version of the theme, so you can always go back to an earlier one.

Work on a copy of your live theme. Customers keep seeing the live theme until you preview the copy and publish it yourself.

  1. Go to Online Store.
  2. Click the name of the live theme, on the image at the top of the page.
  3. Open the Edit code card.
  4. If you see Your plan doesn’t include hosting, click Upgrade plan and choose a plan with Hosting.

If you see Hosting isn’t enabled, Hosting is switched off on the EcomWeb platform, and you cannot turn it on yourself. Contact EcomWeb. If you see neither message, the store is ready.

  1. Install Node.js 24 or later.
  2. Install pnpm.
  3. Install Git.
  4. Install the EcomWeb CLI and sign in. See Install and sign in to the EcomWeb CLI.
  1. Go to Online Store.
  2. On the live theme, open the actions menu (the … button) and choose Duplicate.

The copy appears in your Theme library, with the same settings and the same version in use. Its name is the theme’s name with (bản sao) added. You can rename it from the same menu. The copy counts toward the number of themes your plan allows. If the library is full, delete a theme you do not use or upgrade your plan.

You can also run ecomweb theme duplicate <theme id> and, with --name, choose the copy’s name.

  1. In the Theme library, click the copy’s name.
  2. Open the Edit code card. You can also open it from the … menu of a theme’s row, with Edit code.
  3. In Use the CLI, copy the command of the step Install the CLI and log in and run it in a terminal.
  4. On the Sign in to ecomweb CLI? page, check that the Code matches the one in your terminal, then click Approve.
  5. Copy the command of the step Get the theme’s code and run it in the terminal.

The commands already contain your store ref and the theme id. They look like this:

Terminal window
npm i -g @ecomweb/cli
ecomweb auth login --store-ref <store ref>
ecomweb storefront init --theme <theme id>

ecomweb storefront init creates a new Next.js project folder, installs the dependencies, and saves the theme id as storeThemeId in .ecomweb.json. Every deploy from that folder then goes to the same copy. To put the project in a GitHub repository instead, see Keep the code in a GitHub repo.

  1. Open the project folder in your editor.
  2. Edit pages and components as in any Next.js project.
  3. Run pnpm dev in the project folder.
  4. Open the localhost address the terminal prints. It shows your store’s real data.

The settings a store owner can change in the theme editor are declared in the theme’s settings schema. To see the schema the next deploy will send, run pnpm theme:export.

  1. Run the command of the step Deploy in the project folder.
  2. Wait for the build to finish. The result the terminal prints includes preview_url.
  3. Open the preview on your computer and on your phone.
Terminal window
ecomweb deploy
# If the build fails, read the log of that build
ecomweb logs <build id>

When the build is ready, it becomes the copy’s version in use and a 24-hour preview starts. The Versions card of the copy lists every build, and Build log in the row’s actions shows its log. If a build fails, the theme keeps the version it had. Read the log, fix the code and deploy again.

By default ecomweb deploy also opens your home page once the build is up. If it renders the error page, the command fails with RENDER_ERROR even though the build succeeded. Add --no-render-check to skip that check.

What happens when you deploy to the live theme

Section titled “What happens when you deploy to the live theme”

A build of the live theme would reach customers as soon as it is built, so the CLI does not do that by default.

  • ecomweb deploy --theme <live theme id> is refused with THEME_IS_LIVE: “This theme is live: deploy with –allow-live, or to a draft with –draft”.
  • ecomweb deploy --theme <live theme id> --allow-live ships the build. It goes live once it is built. If the new build never becomes ready, the store keeps its current version.
  • ecomweb deploy --draft deploys to a draft of the live theme instead. On the first use EcomWeb creates the draft from the live theme, named like the theme with (bản nháp) added. Customers still see the live theme.

If you call the deploy API directly, the request takes an allow_live field. When it is left out, a build of a named live theme is accepted and kept in the theme’s versions, but it is not served. Send allow_live: false for a named live theme to get the THEME_IS_LIVE refusal (409) instead.

The Edit code card of the live theme shows the draft route: the step Push to a draft runs ecomweb deploy --draft, and Publish the draft tells you to publish the draft from the theme library. A plain ecomweb deploy in a project whose .ecomweb.json names the live theme is refused in the same way. Prefer a copy of the live theme as in this guide, or the draft.

  1. Go to Online Store.
  2. On the copy’s row in the Theme library, click Publish.
  3. In the Publish this theme? box, click Publish.

You can also publish from the CLI. On a terminal it asks before it publishes. In CI or without a terminal it refuses until you add --yes.

Terminal window
ecomweb theme publish <theme id>

The theme that was live moves to the Theme library. If the new theme has a problem, publish the old one again. See Choose and change your theme.

Every build stays in the theme’s versions.

  1. Open the theme’s page.
  2. In the Versions card, on the version you want, click Use this version. On a narrow screen it is in the row’s actions menu.
  3. If the theme is live, the box tells you what customers will see. Click Use this version, or select Copy before switching first and click Copy and use to try it on a copy.

On a live theme, the version in use keeps serving until the new one is ready. From the CLI:

Terminal window
# List the theme's versions
ecomweb theme versions <theme id>
# Use one of them
ecomweb theme use <theme id> <version id>
# Go back to an earlier build by its build id
ecomweb deployments rollback <build id>

ecomweb theme use on a live theme asks first on a terminal. In CI or without a terminal it needs --yes. A build that failed, or was removed, cannot be used. The version shows the reason.

For the merchant’s view of versions, see Update a theme or go back to an earlier version.

No. Staff cannot use Hosting. Only the store owner can get the code with ecomweb storefront init. Administrators can deploy and publish, from a project the owner created.

You can still get the code, run it on your own server and connect a theme to that website. See Connect a self-hosted site. This works on every plan.

A preview runs for 24 hours after a build becomes the version in use of a theme that is not live. After that, click Preview on the theme to start it again. The live theme previews on the store itself.

The theme keeps the version in use. Run ecomweb logs <build id> or open Build log on the build, fix the code and deploy again. The CLI exits with code 5 when the build failed.