Skip to content

By default, all deployments are assigned a .vercel.app suffixed domain.

This domain can be replaced with a Custom Domain of your choice. This Custom Domain can be purchased with Vercel or a third-party.

In this document, adding a domain to your Vercel projects is explained in detail.

If you want to migrate an existing domain to Vercel, read our Knowledge Base article on Zero-Downtime Migration for DNS.

If you don't own a domain yet, you can purchase it with Vercel. Then, once you own a domain, adding it to a project is very straightforward:

On the dashboard, pick the project to which you would like to assign your domain:

Selecting the project from the Vercel Dashboard.

Once you have selected the project of your choice, click on the Settings tab:

Selecting the Settings tab from the Project Overview page.

Then, select the Domains menu item:

Selecting the Domains menu item from the Project Settings page.

From the Domains page, enter the domain you wish to add to the project:

Entering a domain for the project from the Domains page.

If the domain is in use by another Vercel account, you may be prompted to verify access to the domain. Note that this will not move the domain into your account, but will allow you to use it in your project.

Instructions on verifying a domain by setting a DNS record on the apex domain.

Once the domain has been added, you will be presented with different methods for configuring it, depending on whether it is an apex domain (example.com) or subdomain (docs.example.com).

Apex domains can be configured with a A record, while subdomains can be configured with a CNAME record. Both domain types can also be configured using the Nameservers method.

You can configure apex domains either with a A record or through the Nameservers method.

Instructions on configuring an apex domain from the Project Domains page.

You can configure subdomains either with a CNAME record or through the Nameservers method.

Instructions on configuring a subdomain from the Project Domains page.

When selecting the Nameservers method of configuration for either apex domains or subdomains, you will be provided with the Vercel nameservers to copy and use with your registrar.

Once the domain has been configured, the card status will change to reflect this.

A configured domain on the Project Domains page.

If a user visits your domain with or without the "www" subdomain prefix, we will attempt to redirect them to your domain. For more robust protection, you should explicitly add this domain and redirect it.

Once a domain has been added, all of its DNS Records can be found in the Advanced Settings page. From there, you can view and manage the records.

On the dashboard, click on the Domains tab:

Selecting the Domains tab from the Vercel Dashboard page.

Once on the Domains tab, click on a domain of your choice to view its Advanced Settings page.

Selecting the domain to view its Advanced Settings page.

Once on the Advanced Settings page of your domain, fill out the DNS Record form and click on the Add button.

DNS Records form to add a new DNS Record.

Using the form mentioned above, you can then add the DNS Record of your choice. The following types are supported:

  • A
  • AAAA
  • ALIAS
  • CAA
  • CNAME
  • MX
  • SRV
  • TXT

Vercel does not provide an email service. To be able to receive emails through a Domain that you've added to Vercel, you need to add the respective DNS Records of type MX.

For most common third-party email providers, Vercel helps with this process by allowing you to add those missing DNS Records using so-called DNS Email Presets on your dashboard.

In order to make use of them, navigate to the Domains page of your Personal Account or Team, click the Domain of your choice and click the Add Email Preset button on the right:

Adding a DNS Email Preset by clicking the Add Email Preset button.

You will be presented with a list of commonly used third-party email providers. If yours is in the list, select it and the necessary MX DNS Records will automatically be configured on your Domain.

If your email provider is not in the list, please refer to their documentation and dashboard to find out which MX DNS Records you need to add.

For domains with Vercel as the registrar, nameservers can be viewed, edited, and reset on the Advanced Settings page.

Nameserver changes can take up to 48 hours to complete due to DNS propagation.

On the Advanced Settings page of your domain, click the Edit button.

Opening the Edit Nameservers modal by clicking the Edit button.

After clicking the Edit button, the Edit Nameservers modal will open up. When submitting your nameserver changes, a message will appear upon successful submission.

Adding custom nameservers by clicking the Apply button.

If you wish to revert back to the nameservers you were using before your custom nameservers change, click on the Restore Original Nameservers button. After clicking on the Restore Original Nameservers button, the Restore Original Nameservers modal will open up, confirming which nameservers will be present after the change. When submitting your nameserver changes, a message will appear upon successful submission.

Restoring original nameservers by clicking the Restore button.

You can use your Custom Domain as a Wildcard Domain by prefixing it with *..

Note: If using your Custom Domain as a Wildcard Domain, you must use the nameservers method for verification.

To add a Wildcard Domain, follow the steps to add a domain. At step 3, use the prefix * (e.g. *.acme.com).

A Wildcard Domain being deployed.

After the verification process is complete, the status of the domain will be updated within the UI to confirm that it is ready for use.

Note: It is not possible to use a multi-level wildcard subdomain, it is only possible to use a subdomain at one level down.

Once the domain has been added to your project and configured, it is automatically applied to your latest deployment.

Note: The first deployment of a new project will be marked as production and subsequently assigned with your custom domain automatically.

When a Custom Domain is assigned to a project that's using Git, each push (including merges) to the Production Branch (commonly main) will trigger a deployment to the defined domain.

Reverts take effect immediately, assigning the Custom Domain to the deployment made prior to the point the revert is effective from.

You can add domain redirects from the Domains tab when more than one domain is present in the project. This provides a way to, for example, redirect a www subdomain to an apex domain, but can be used in a variety of ways.

If a user visits your domain with or without the "www" subdomain prefix, we will attempt to redirect automatically. You might still want to add this redirect explicitly.

To add a redirect, click the Edit button on the domain you want to redirect from and use the Redirect to dropdown to select the domain you want to redirect to:

A domain redirect that redirects requests made to www.acme.com to acme.com.

A domain redirect can be temporary or permanent by specifying a status code.

  • 307 Temporary Redirect - not cached by client, method and body never changed.
  • 302 Found - not cached by client, method may or may not be changed to GET.
  • 308 Permanent Redirect - cached by client, method and body never changed.
  • 301 Moved Permanently - cached by client, method may or may not be changed to GET.

We recommend using status code 307 or 308 to avoid the ambiguity of non-GET methods, which is necessary when your application needs to redirect a public API.

Internet Explorer on Windows 8 and older does not support 308 natively, but Vercel supports older browsers by adding a Refresh header.

Adding an apex domain to a Project on Vercel will automatically suggest adding its www counterpart. Using both of these domains ensures that visitors can always access your site, regardless of whether or not they use www when entering the URL.

After clicking "Add" for a domain, you will be able to choose how to redirect the www counterpart:

Selecting the Domains tab from the Vercel Dashboard.

We recommend using the www subdomain as your primary domain, with a redirect from the non-www domain to it. This allows the Vercel Edge Network more control over incoming traffic for improved reliability, speed, and security. The redirect is also cached on visitor's browsers for faster subsequent visits.

Some browsers like Google Chrome automatically hide the www subdomain from the address bar, so this redirect may not affect your URL appearance.

Choosing to redirect the www domain to the non-www also works but provides Vercel less control over incoming traffic. Alternatively, you can choose to add only the domain you typed.

Additional technical information about Domain redirects

Using CNAME instead of A records ensures that domains on Vercel are fast, reliable, and fault-tolerant.

Unlike A records, CNAME records avoid hard-coding a specific IP address in favor of an additional lookup at the DNS level. This means that Vercel can quickly steer traffic in the case of DDoS attacks or for performance optimizations.

Unfortunately, the DNS spec forbids using CNAME records on apex domains like example.com. They are, however, allowed for subdomains like www.example.com. This is why Vercel recommends primarily using a www domain with a CNAME record, and adding a redirect from the non-www domain to it.

While we recommend using www as described above, Vercel maximizes the reliability and performance of your apex domain if you choose to use it as your primary domain by leveraging the Anycast methodology. This means Vercel still supports geographically routed traffic at infinite scale if you use an A record.

Custom Domains purchased through or registered with Vercel are automatically renewed by default. You can choose to prevent the automatic renewal of a Domain from the Domains tab on the Vercel Dashboard:

Selecting the Domains tab from the Vercel Dashboard.

Once on the Domains tab, click on a Domain of your choice to view its Advanced Settings:

Selecting the Domain to view its Advanced Settings.

The auto renewal status of your Domain is displayed here as either "on" or "off":

The auto renewal status for this Domain is currently off.

You can toggle auto renewal from the details menu in the top right:

The menu item for toggling the auto renewal status of your Domain.

If auto renewal is off, Vercel will not try to re-register the Domain when it expires at the end of the registration period. You will not be charged for the Domain any longer, but you will lose access to the Domain when it expires. Recovering the Domain, if even possible, may be subject to a redemption fee of $85 USD. Please contact our support team as soon as possible.

Vercel will send you three emails regarding the Domain before this happens. 24 and 14 days before the Domain is set to expire, you will be notified that auto renewal is off and the Domain will expire soon. A final email will notify you when the Domain expires.

If auto renewal is on, Vercel will begin daily attempts to renew the domain one week before the domain expires. You will receive three emails regarding the renewal process: 17 days and 7 days before renewal attempts begin, and finally when the Domain has either been successfully renewed or failed to renew.

Note: Renewal attempts may begin earlier than 7 days in advance for certain TLDs.

Third-Party Domains (ones not purchased with or transferred into Vercel) are not subject to auto-renewal. Please refer to your Domain name registrar's policy regarding renewals.

You can move domains to another profile or team using the Domains tab from the Vercel Dashboard.

Selecting the Domains tab from the Vercel Dashboard page.

Once on the Domains tab, select the domain(s) you wish to move by using the checkbox next to each domain then click Move.

Selecting which domains to move from the Domains tab.

After selecting the domain(s) and clicking Move, you will be asked to confirm which profile or team you wish to move them to.

Entering a new profile or team destination for a domain.

When selecting the input field, you will be provided with a list of teams you belong to. If the profile or team you wish to move the domain(s) to is not present, enter the slug value instead. You can find the slug value in Settings page for both profiles and teams.

Note: When moving domains to another team or profile, they will be removed from all projects they are currently part of.

To confirm the change, select Move. The domains will be transferred to the new profile of team immediately.

For domains that are registered with Vercel, you can retrieve an authorization code for transferring out to another registrar from the Domains tab of the Vercel dashboard.

Selecting the Domains tab from the Vercel Dashboard page.

Once on the Domains tab, click on the triple-dot menu trigger button for the relevant domain, a menu-item button to transfer the domain out will be presented if the domain is registered with Vercel.

Menu item button for getting domain's transfer authorization code.

Note: If under a Team scope, only Team Owners will see the menu-item button.

After clicking the menu-item button, a modal will open up with the authorization code required to transfer the domain. Transferring a domain can take up to a week.

Menu item button for getting domain's transfer authorization code.

Every commit pushed to the Production Branch of your connected Git repository will be assigned the domains configured in your project.

In order to automatically assign a domain to a different branch, you can enter it in the Git Branch field of your Domain:

A Custom Domain that is automatically assigned to the staging Git Branch.

To remove a domain that is assigned to a project, navigate to the Domains tab from the Project Overview and click the Edit button for the domain you want to remove:

A configured domain on the Project Domains page with the option to edit.

Once the Edit button has been clicked, you will be presented with further options. Click the Remove button to remove the domain from the project:

A configured domain on the Project Domains page with the option to remove.

At this point, if you wish to remove a domain from all Projects, as well as your Account, you can complete this by selecting the checkbox and clicking on the Remove button to remove the domain from all places.

The confirmation modal to remove a domain from the Account entirely.

When you connect a domain to a Project, Vercel checks if this domain is already associated with a Personal Account or Team. A domain can only be associated with one Personal Account or Team at a time.

The following table shows potential errors that can be encountered when adding a domain to your project:

Error Text
Description
This team has already registered this domain
The domain you are trying to add is already connected to the team you have selected.
You have already registered this domain
The domain you are trying to add is already connected to the Personal Account you have selected.
The domain mydomain.com is not available
This more generic error message states that the domain is owned by another Vercel account that you do not have access to. If you have ownership of the domain in question, contact Vercel support to request that the domain be moved or delegated to your account.

Domain ownership errors

When you add a domain to Vercel with the Cloudflare Proxy enabled, you need to ensure Vercel can issue and renew a certificate to communicate securely with Cloudflare. Since Let's Encrypt uses HTTP challenges to issue certificates, the path associated to HTTP challenges needs to remain accessible without interference from Cloudflare. Follow the steps below for a successful domain configuration between Vercel and Cloudflare:

  1. Configure your domain such that HTTPS is disabled for the path /.well-known/**.
  2. Run curl http://<domain>/.well-known/acme-challenge (Replace <domain> with your domain. Notice that it’s http and not https).

If the above curl command returns an error (e.g. {"error":{...}}), then you’re good to go - it means that Vercel can generate certificates successfully. Otherwise, make sure that SSL is disabled for /.well-known/acme-challenge/** and try again.

Warning: A domain with the Cloudflare Proxy turned on can introduce unpredictable cache behavior depending on the configuration of the Cloudflare dashboard. We recommend all domains using the Cloudflare Proxy with Vercel to avoid caching pages so Vercel can serve the latest content of your deployments without any interference.

For more information on what to do next, we recommend the following article: