Skip to content

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.

  1. Sign in to the CLI.
  2. Run the command below to create a Next.js storefront project for your store.
  3. Put the project on your server, for example a Vercel project, so it has an https address.
Terminal window
# Create a Next.js project for the selected store
ecomweb storefront init

Only 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.

Connect on a copy so customers are not sent away before your site is ready.

  1. Go to Online Store.
  2. 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.

  1. In the Theme library, open the actions menu on the copy’s row and choose Switch to Self-hosted.
  2. Enter the Site URL, for example https://shop.example.com.
  3. 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.
  4. 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 localhost can use http.
  • A * wildcard only works inside the first part of the domain, for example https://shop-*-team.vercel.app. A pattern like *.vercel.app is refused.

The site URL and these domains are added to the list of sites that can use the publishable key.

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.

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:

Terminal window
# Run in the project folder
ecomweb 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.

  1. Open your site and check that it works.
  2. Go to Online Store.
  3. On the copy’s row in the Theme library, click Publish.
  4. 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.

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.

  1. Open the connected theme’s page.
  2. Open the actions menu at the top of the page and choose Manage Self-hosted.
  3. In the Site in use card, click Edit.
  4. 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.

Publish another theme in Online Store, or choose Use this version on an earlier version in the theme’s Versions card.