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.

This works on every plan. You can still edit the theme's settings in the dashboard.

Get the storefront code

1. Install the EcomWeb CLI. See Install and sign in to the EcomWeb CLI.
2. Sign in to the CLI.
3. Create a storefront project for your store with the command below.
4. 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 store
$ ecomweb storefront init

Only the store owner can create a project, because the command needs the store’s publishable key. The project needs Node.js 24, pnpm and Git on your computer. Any place that can run Next.js works.

Duplicate a theme to connect

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

1. Go to Online Store.
2. On the current theme, click the three dots next to the Customize button.
3. Select Duplicate.

The copy is in your Theme library, named after the theme with (bản sao) added. The copy counts toward the number of themes your plan allows.

Connect the copy to your site

1. In the Theme library, click the three dots on the copy’s row.
2. Select Switch to Self-hosted.
3. Enter the Site URL, for example https://shop.example.com.
4. 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.
5. 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. Allowed domains takes up to 20 addresses. The site URL and these domains are automatically added to the list of sites that can use the publishable key.

Set environment variables on your server

After you connect, the page has an Environment variables card with the variables your site needs to read your store’s data and settings.

1. In the Environment variables card, copy the ECOMWEB_STORE_REF, ECOMWEB_PUBLISHABLE_KEY and ECOMWEB_API_URL lines.
2. Add these variables to the environment settings on your server.
3. Add a SITE_URL variable set to your site’s address.
4. Build and run your site again.

These variables are built into the code at build time, so you need to build again every time you change one.

Push theme settings to EcomWeb

To edit the theme’s settings in the dashboard, push the project’s schema after every change, for example in CI. The command is in the Theme settings card, with your theme ID already filled in.

# Run in the project folder
$ ecomweb theme schema push --theme <theme id>

In CI, use an API key with the deploy:storefront scope. See Create and manage API keys.

Publish the connected theme

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.

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.

1. Add the domain where your site runs.
2. Change the domain’s DNS as that provider tells you.
3. Open the connected theme’s page.
4. Click the three dots at the top of the page.
5. Select Manage Self-hosted.
6. In the Site in use card, click the pencil icon Edit.
7. Enter the new address in Site URL.
8. Click Save.

The new address is added as a version and used right away. If this is the current theme, the confirmation box 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 creating a new version.

Frequently asked questions