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.
Check that the store has Hosting
Section titled “Check that the store has Hosting”- Go to Online Store.
- Click the name of the live theme, on the image at the top of the page.
- Open the Edit code card.
- 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.
Prepare your computer
Section titled “Prepare your computer”- Install Node.js 24 or later.
- Install pnpm.
- Install Git.
- Install the EcomWeb CLI and sign in. See Install and sign in to the EcomWeb CLI.
Duplicate the live theme
Section titled “Duplicate the live theme”- Go to Online Store.
- 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.
Get the copy’s code
Section titled “Get the copy’s code”- In the Theme library, click the copy’s name.
- Open the Edit code card. You can also open it from the … menu of a theme’s row, with Edit code.
- In Use the CLI, copy the command of the step Install the CLI and log in and run it in a terminal.
- On the Sign in to ecomweb CLI? page, check that the Code matches the one in your terminal, then click Approve.
- 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:
npm i -g @ecomweb/cliecomweb 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.
Edit and run it locally
Section titled “Edit and run it locally”- Open the project folder in your editor.
- Edit pages and components as in any Next.js project.
- Run
pnpm devin the project folder. - 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.
Deploy and preview
Section titled “Deploy and preview”- Run the command of the step Deploy in the project folder.
- Wait for the build to finish. The result the terminal prints includes
preview_url. - Open the preview on your computer and on your phone.
ecomweb deploy# If the build fails, read the log of that buildecomweb 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 withTHEME_IS_LIVE: “This theme is live: deploy with –allow-live, or to a draft with –draft”.ecomweb deploy --theme <live theme id> --allow-liveships the build. It goes live once it is built. If the new build never becomes ready, the store keeps its current version.ecomweb deploy --draftdeploys 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.
Publish the copy
Section titled “Publish the copy”- Go to Online Store.
- On the copy’s row in the Theme library, click Publish.
- 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.
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.
Roll back to an earlier build
Section titled “Roll back to an earlier build”Every build stays in the theme’s versions.
- Open the theme’s page.
- 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.
- 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:
# List the theme's versionsecomweb theme versions <theme id># Use one of themecomweb theme use <theme id> <version id># Go back to an earlier build by its build idecomweb 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.
Can staff do this?
Section titled “Can staff do this?”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.
My plan has no Hosting. What can I do?
Section titled “My plan has no Hosting. What can I do?”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.
How long does a preview stay open?
Section titled “How long does a preview stay open?”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.
What if the build fails?
Section titled “What if the build fails?”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.