Conceptual

Working with domains

Learn how domains work and the options Vercel provides for managing them.
Table of Contents

When you create a deployment on Vercel, we automatically assign it a domain based on your project name and ending in .vercel.app. Your site will be available to anyone that you share the domain with.

More often than not, you will want to assign a domain to a project that reflects its nature better. You can buy a domain name either through Vercel or through a third-party. Depending on which option you choose, will dictate how and when you'll need to make configurations:

When you buy a domain through Vercel, we configure and set the nameservers, which means you do not need to set any DNS records or make any configurations. It just works. In addition, if you choose to make configurations, such as setting up email, it's all maintained from the Domains tab of either your Account Settings page (account-scoped domains) or your team's dashboard. Finally, all renewals, including domain and SSL certificate renewals are automatically handled by Vercel.

When you buy a custom domain through a third-party, you can use the add a custom domain workflow to configure the DNS records. If you are using Vercel's nameservers, you can manage certain settings, such as records for email providers or additional DNS records through the Domains tab of either your Account Settings page (account-scoped domains) or your team's dashboard. Otherwise, you must configure nameservers and DNS records through your domain registrar.

When you are using domains with Vercel, there are two areas of the dashboard that you may need to go to in order to configure them correctly. The first relates to your ownership and the second relates to configuring the domain for your Project:

  • Domain ownership: Domains can be owned by your account or by a specific team. Account-scoped domains can be accessed from the Domains tab on your Account Settings page. Team-scoped domains can be accessed from the Domains tab on your team's dashboard. All your domains, regardless of where they are registered, are listed here and are owned by you. If you are using Vercel's nameservers, which is the case by default if you buy your domain through Vercel, you can manage DNS records, custom nameservers, and SSL certificates here. Domains that are registered by a third-party should manage DNS records and nameservers with the third-party.

  • Project assignment: This is accessed by selecting the project that you wish to assign the domain to and navigating to Settings > Domains. From here you can add an apex domain or subdomain to the Project. When a user visits your domain, they will see the most recent production deployment of your site, unless you assign the domain to a Git branch or add redirection.

When you add a domain to Vercel for the first time, it will appear as an apex domain in your Domains tab. If you add that domain (for example, yourdomain.com, or docs.yourdomain.com) to a project on a different Vercel scope, that domain will require a TXT Verification step and will only show up at the project level. The apex domain will still appear in the original account's Domains tab.

Managing your domains under your account provides an additional layer of protection over managing them under a team. Your account will always be yours, no matter what, whereas teams can transfer ownership to different users. If the domains should always be owned and paid for by you, they belong under your account. If the domains should always be owned and paid for by the team (regardless of who owns the team in the future), they belong under the team.

The apex domain is the root-level domain, such as acme.com. When you add an apex domain, Vercel will recommend that you add a redirect to a www subdomain. This is because www records allow for better control over your domain. Anything configured on the apex domain (for example, cookies or CAA records), will usually apply to all subdomains, rather than setting it on the www subdomain, which will only apply to your www record. In addition, because Vercel's servers use anycast networking, it can handle CNAME records differently, allowing for quicker DNS resolution and therefore a faster website experience for the end user.

A subdomain is a more specific part of that domain that can be assigned to a particular part of your site, for example, blog.acme.com, help.acme.com. This helps to blend both your brand, with the specificity of where the user may need to go. To add a subdomain to your Project, follow the instructions in the Add a custom domain doc. If you have bought the domain through Vercel, you can also point a subdomain to an external service through the Domains section of the dashboard. Subdomains are set through a CNAME DNS record.

Image showing the fully-qualified domain name (FQDN).

You can also configure wildcard domains. Using a wildcard domain, such as *.acme.com, is a way to scale and customize your project on Vercel. Rather than specifying a particular subdomain, you can add a wildcard domain to your project, and then will need to set the nameservers to the intended nameservers, allowing the domain to be resolved. See the static.fun example to see how to use Wildcard domains on Vercel.

To add a wildcard domain, follow the steps in Adding a domain.

Wildcard domains must be configured with the nameservers method. This is because in order to generate the wildcard certificates, Vercel needs to be able to set DNS records, since the service that Vercel uses to generate those requires us to solve a challenge to verify ownership.

When you create a domain, you may want to also set up a way for users to contact you through an email address that is pointed at that domain. Vercel does not provide a mail service for domains purchased with or transferred into it.

Because many domain providers do not offer a mail service, several third-party services specifically offer this type of functionality and are enabled by adding MX records. Examples of this type of service include ImproxMX and Forward Email, however there are many more options available. For each provider, different DNS records are required to be added. For information on how to set up email, see How do I send and receive emails with my Vercel purchased domain?

Invalid domain configurations are one of the most common types of domain issues on Vercel. To learn more about other common domain issues, see the troubleshooting doc.

Last updated on October 6, 2024