Connect a self-hosted site
You run the storefront code on your own server, for example Vercel or a VPS, and still use EcomWeb’s products, orders and settings. Once the connected theme is published, your store’s EcomWeb address sends customers to your site.
You need the EcomWeb CLI signed in, Node.js 24, pnpm and Git. See Install and sign in to the EcomWeb CLI. You can still edit the theme’s settings in the dashboard.
Get the storefront code
Section titled “Get the storefront code”- Sign in to the CLI.
- Run the command below to create a Next.js storefront project for your store.
- Put the project on your server, for example a Vercel project, so it has an https address.
# Create a Next.js project for the selected storeecomweb storefront initOnly the store owner can create a project, because the command reads the store’s publishable key. Any place that can run Next.js works. To edit the code with an AI assistant first, see the theme code guide.
Duplicate a theme to connect
Section titled “Duplicate a theme to connect”Connect on a copy so customers are not sent away before your site is ready.
- Go to Online Store.
- Open the actions menu of the current theme and choose Duplicate.
The copy appears in your Theme library. You can rename it. The copy counts toward the number of themes your plan allows.
Connect the copy to your site
Section titled “Connect the copy to your site”- In the Theme library, open the actions menu on the copy’s row and choose Switch to Self-hosted.
- Enter the Site URL, for example
https://shop.example.com. - If your site also runs at other addresses, such as a preview on Vercel, enter them under Allowed domains, one per line, without a path.
- Click Connect.
Your site is added as a version of the copy and used right away. The old version stays in Versions, so you can switch back.
- The Site URL must use https.
- Allowed domains takes up to 20 addresses. Only
localhostcan use http. - A
*wildcard only works inside the first part of the domain, for examplehttps://shop-*-team.vercel.app. A pattern like*.vercel.appis refused.
The site URL and these domains are added to the list of sites that can use the publishable key.
Set the environment variables
Section titled “Set the environment variables”After you connect, the theme’s page has an Environment variables card with the values your site needs.
| Variable | Value |
|---|---|
ECOMWEB_STORE_REF |
The reference of your store |
ECOMWEB_PUBLISHABLE_KEY |
The store’s publishable key |
ECOMWEB_API_URL |
The API address, https://apibase.ecomweb.app/api/v1 |
SITE_URL |
Your site’s address |
Copy the first three from the card and set SITE_URL yourself. Add all four to the environment settings on your server, then build and run your site again. The project reads these values at build time, so build again every time you change one.
Only the store owner can see the publishable key. Others get the key from the store owner, who can find it in Settings › API Keys. For how the key is used, see Create and manage API keys.
Push theme settings from CI
Section titled “Push theme settings from CI”To edit the theme’s settings in the dashboard, push the project’s settings schema after every change, for example in CI. The Theme settings card shows the command with your theme ID filled in:
# Run in the project folderecomweb theme schema push --theme <theme-id>In CI, use an API key with the deploy:storefront scope. A key with write:settings also works. See the scopes guide.
Publish the connected theme
Section titled “Publish the connected theme”- Open your site and check that it works.
- Go to Online Store.
- On the copy’s row in the Theme library, click Publish.
- In the Publish this theme? box, click Publish.
From now on, customers who visit your store’s EcomWeb address are sent to your site, keeping the same path. EcomWeb stops hosting the storefront.
Keep the required paths
Section titled “Keep the required paths”Use your own domain
Section titled “Use your own domain”To let customers reach your site on your own domain, point that domain to your server, not to EcomWeb. For example, add the domain in Vercel and change its DNS as that provider tells you. Then tell EcomWeb the new address.
- Open the connected theme’s page.
- Open the actions menu at the top of the page and choose Manage Self-hosted.
- In the Site in use card, click Edit.
- Enter the new address in Site URL and click Save.
The new address is added as a version and used right away. If this is the live theme, the confirmation asks you to click Open site to check your site first, and only then can you click Use this version. If you only change Allowed domains, the change is saved right away without a new version.
I can’t see the publishable key in the Environment variables card
Section titled “I can’t see the publishable key in the Environment variables card”Only the store owner can see it. Ask the owner to copy it from Settings › API Keys.
My site on Vercel is rejected when it calls the API from a preview
Section titled “My site on Vercel is rejected when it calls the API from a preview”Add the preview address to Allowed domains, for example https://shop-*-team.vercel.app. The * only works in the first part of the domain.
How do I go back to an EcomWeb theme?
Section titled “How do I go back to an EcomWeb theme?”Publish another theme in Online Store, or choose Use this version on an earlier version in the theme’s Versions card.