Skip to content

EDU-15536: Add info about single domain unification #2034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

EDU-15536: Add info about single domain unification #2034

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3a416f9
Add info about single domain unification
mariana-caetano Jun 27, 2025
ed40c46
Update Step 3 and 5 instructions
mariana-caetano Jun 27, 2025
69b596a
Remove tag
mariana-caetano Jun 27, 2025
c5c02a2
Fix instructions 7 and 8
mariana-caetano Jun 27, 2025
cf442d7
Fix tag
mariana-caetano Jun 27, 2025
0121919
Review steps
mariana-caetano Jun 27, 2025
4d04605
Review 'Stores hosted on Vercel'
mariana-caetano Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 70 additions & 7 deletions docs/faststore/docs/go-live/1-configuring-external-dns.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: '1. Configuring external DNS'
---

In this guide, you will learn how to configure external domains for your **FastStore** and **VTEX** website. The process involves the following steps:
In this guide, learn how to configure external domains for your **FastStore** and **VTEX** website. The process involves the following steps:

- Setting up your external DNS provider to point your custom domain to your VTEX website. You can buy custom domains from any **domain registration platform**.
- Configuring your custom domains in **VTEX Account Settings**.
Expand Down Expand Up @@ -45,19 +45,35 @@ Now, you must set up your VTEX account to use the DNS records created in the pre
4. In the **Hosts** field, enter your main domain (example: `www.mystore.com`) into the list.
5. Click `Add`.
6. Add the `secure` subdomain (example: `secure.mystore.com`) to the list.

![host-configuration](https://vtexhelp.vtexassets.com/assets/docs/src/account-settings-new___2e13bee3041e8505922a737b94652ca6.png)

7. Add the root domain as well; for example, if your domain is `www.mystore.com`, add `mystore.com`. For a complete setup, you must add three hosts for each domain:
- `www.mystore.com` (store domain)
- `www.mystore.com` (store domain)
- `mystore.com` (root domain)
- `secure.mystore.com` (checkout/myaccount subdomain)

> ⚠️ To ensure a seamless checkout experience, all subdomains used by your store must be added to the host list. For more information, see the [Adding subdomains to the host list](#adding-subdomains-to-the-host-list) section.
<details>
<summary><b>Stores hosted on Vercel</b></summary>

Stores hosted on [Vercel](https://vercel.com/) can use a single domain for all pages, including Checkout and My Account. This eliminates the need for a separate `secure.domain.com` subdomain (e.g., everything routes through `www.domain.com`).

Add the hosts for the domain as shown in the example below:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we are using this approach of a single domain for stores hosted on Vercel, are these instructions correct when setting up the hosts on VTEX Admin?

single-domain-step3


- `www.mystore.com` (store domain)
- `mystore.com` (root domain)

For more information about the single domain feature, see the [Step 5 - Single-domain setup (Only for stores hosted on Vercel)](#step-5---single-domain-setup-only-for-stores-hosted-on-vercel).
</details>

8. Click the **Save** button.

> ⚠️ To ensure a seamless checkout experience, all subdomains used by your store must be added to the host list. For more information, see the [Adding subdomains to the host list](#adding-subdomains-to-the-host-list) section.

### Step 4 - Associating your custom domain with your FastStore project

> ⚠️ Stores hosted on [Vercel](https://vercel.com/), see the [Step 5 - Single-domain setup (Only for stores hosted on Vercel)](#step-5---single-domain-setup-only-for-stores-hosted-on-vercel).

Back to your FastStore project, you must also configure your project to point to the right addresses and domains.

1. Open your FastStore project in any code editor of your preference.
Expand Down Expand Up @@ -103,7 +119,54 @@ Take the following example of how this code block would look after configuring a

> ⚠️ For stores with prefixed domains, add the `subDomainPrefix` property to `discovery.config.js` to ensure product visibility in the secured environment. For more information, see the [Adding `subDomainPrefix` for prefixed domains](#adding-subDomainPrefix-for-prefixed-domains) section.

### Step 5 - Configuring the CDN workflow (Only for new go-lives)
### Step 5 - Single-domain setup (Only for stores hosted on Vercel)

Stores hosted on [Vercel](https://vercel.com/) can benefit from a single domain. This feature simplifies domain management by routing Checkout and My Account pages through the store’s primary domain (e.g., `www.domain.com`), removing the need for a separate `secure.domain.com` subdomain. To use this feature, follow these instructions:

#### Check the store configuration file and store version

1. Check if you have renamed the configuration file name from `faststore.config.js` to `discovery.config.js`. For more information, see this [release note](https://developers.vtex.com/updates/release-notes/2024-12-16-discovery-config-file).
2. Check if the `@faststore/cli` is listed as a dependency of your store `package.json`. For more information, see this [release note](https://developers.vtex.com/updates/release-notes/2024-09-11-faststore-cli-dependency).
3. Make sure your FastStore project is on version `3.6.0` or later. To update your store to the latest version, open your FastStore project in a code editor of your preference.
4. Open the terminal and run the following command to update FastStore packages:

```bash
yarn upgrade -L --scope @faststore
```

#### Open a ticket to VTEX Support

To enable the single-domain feature, request the account configuration from VTEX. This ensures proper routing and security settings for your store. Open a ticket with [VTEX Support](https://help.vtex.com/en/support) requesting that the account be configured for a single-domain setup. Please include the following information in the ticket:

- Account name.
- [FastStore store version](https://developers.vtex.com/docs/guides/faststore/getting-started-faststore-versions-and-support-levels).
- Final domain name.

>⚠️ For existing stores that set up the single domain before June 26, 2025, you must open a new ticket to request re-implementation, as the feature has been improved since then.

#### Update the `discovery.config.js` file

1. After receiving [confirmation that the single-domain setup is configured](#open-a-ticket-to-vtex-support), go back to the FastStore project in a code editor.
2. Go to the `discovery.config.js` file, update the `Production URLs` field with the new URLs, and replace the `rootDomain` value with your store root domain name. See the example below:

```js
...

// Production URLs
storeUrl: "https://www.{rootDomain}.com",
secureSubdomain: "https://www.{rootDomain}.com",
checkoutUrl: "https://www.{rootDomain}.com/checkout",
loginUrl: "https://www.{rootDomain}.com/api/io/login",
accountUrl: "https://www.{rootDomain}.com/api/io/account",

...
```

3. Save your changes.
4. Open the `vtex.env` file.
5. Add the `SITE_HOST` key with the main domain as the value specified in [Stores hosted on Vercel in Step 3 - Configuring domains in VTEX Account Settings](https://developers.vtex.com/docs/guides/faststore/go-live-1-configuring-external-dns#step-3-configuring-domains-in-vtex-account-settings).

### Step 6 - Configuring the CDN workflow (Only for new go-lives)

If your FastStore website is going live for the first time, [open a ticket with VTEX Support](https://help.vtex.com/en/support) and specify that you need to configure the CDN workflow for your store's secure and main domains.

Expand All @@ -114,7 +177,7 @@ Include the following information in your ticket:

The VTEX team will evaluate your request and take the necessary actions to configure your account's CDN workflow.

### Step 6 - Adding your store domain to FastStore WebOps
### Step 7 - Adding your store domain to FastStore WebOps

To finish the domain configuration, add your store domain to [FastStore WebOps](https://developers.vtex.com/docs/guides/faststore/1-onboarding-overview).

Expand All @@ -127,7 +190,7 @@ To finish the domain configuration, add your store domain to [FastStore WebOps](

![adding-host-webops](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/faststore/docs/go-live/adding-host-webops.png)

### Step 7 - Monitoring the new deployment
### Step 8 - Monitoring the new deployment

After adding your domain to FastStore WebOps, a new deployment will be triggered automatically. Before proceeding to the next step, monitor the deployment progress in the FastStore WebOps dashboard until it is fully completed.

Expand All @@ -139,7 +202,7 @@ Then, check if your domain is configured correctly in the FastStore WebOps envir

![currrent-domains](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/faststore/docs/go-live/current-domains.png)

### Step 8 - Migrating the domain
### Step 9 - Migrating the domain

1. Open a ticket to [VTEX Support](https://help.vtex.com/en/support) requesting a **domain migration** for your FastStore WebOps implementation. Please include the following information:
- VTEX account name
Expand Down
Loading