Domains Overview

A domain is a user-friendly way of referring to the address access a website on the internet. For example, the domain you're reading this on is vercel.com. Domains can be analogous to the address where your house is. When someone sends a letter to your house, they don't need to know exactly where it is, they just need the address and the relevant post office handles routing the letter.

The system that manages the details about where a site is located on the internet, is known as DNS or the Domain Name System. At its most basic, DNS maps human-readable domain names to computer-friendly IP addresses. When you request a site in your browser, the first step is converting the domain address to an IP address. That process is handled by DNS and called DNS Resolution. Understanding how DNS works is important to ensure that you are configuring your domain correctly.

Diagram showing the a basic DNS query.

1. You enter vercel.com in your browser. Your browser will first check its local DNS cache to see if it knows the IP address of vercel.com. If it does, it will request the site from that address.

2. Your browser initiates a DNS query through a server known as a recursive resolver, usually provided by your ISP or a third-party. The recursive resolver acts as a middleman between the browser and DNS server and is used to increase the speed and efficiency of the resolution process. The resolver will check its cache first to see if it already has the IP address. If it doesn't, it'll request the IP address from a DNS server.

3. There is a network of DNS servers, in a hierarchy, located all around the world. The recursive resolver will query in the following pattern:

   • At the entrance to the network are 13 root nameservers. These are the servers that will be contacted first. The root server will look at the domain name, and based on the TLD or top-level domain (.com, .co.uk, etc.), will direct the resolver to the correct TLD server.
   • The TLD nameservers store information about domain names that belong to the same TLD. For example, when searching for vercel.com, once the recursive resolver receives a response from the root nameserver, it will query the .com TLD nameserver.
   • This TLD server will then respond resolver with details about the authoritative nameserver that has the IP address mapping for vercel.com stored in an A record. The authoritative nameserver returns this record to the recursive resolver, which will cache the result and return it to your browser.

4. Once your browser has the IP address, an HTTP request is made by the browser to the web server located at that IP address.

This overview shows a point of view of a user visiting your site. But what does this look like when you're the developer creating a site?

When you've created a Project and deployed it on Vercel, your site lives on Vercel's web servers, which we know to be at the IP address 76.76.21.21. However, your user's browser doesn't know that. For this reason, the browser will perform a DNS Lookup to retrieve the correct IP mapping to yoursiteaddress.com from a DNS server.

Diagram showing the Vercel-hosted query.

This is where, as a developer, you may have to configure the DNS settings to tell the authoritative server exactly where your site lives. Vercel guides you through exactly what information you need to set, within your Dashboard. There are a number of different settings that you should be aware of:

• DNS records: DNS records are an entry in a database that maps the domain with the IP address, which is then stored on the authoritative server. Some of the most common record types are: CNAME (Canonical name), A (Address), NS (nameserver), and MX (mail exchange). These are all described in more detail below.
• Nameserver: Nameservers are an important part of the DNS. They refer to the actual server that maintains and manages the DNS records. There are three types of nameservers: root nameserver, TLD nameserver, and the authoritative server. You can learn more about using a nameserver with Vercel below.
• SSL Certificates: SSL Certificates are a way to show that there is a secure connection from your domain to your website. These are described in more detail below.

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 section of the 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 section of the dashboard. Otherwise, you must configure nameservers and DNS records through your domain registrar.

It's important to note that 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: You can access this by selecting the Domains tab on your Vercel Dashboard. All 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.

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 via 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?

As mentioned above, DNS is the system used to connect domain names to IP addresses. When you make a request for a website, the browser performs a DNS query. It's usually the recursive resolver that carries out this work, going to the root DNS nameserver, TLD nameserver, and the authoritative server, if it isn't found in the cache.

DNS configuration with multiple DNS record types

There are a number of different types of DNS records that can be used together to create a DNS configuration. Some of the common information that you might see in a DNS record are:

• Host Name: The hostname of www
• IP Address or URL: The IP address (or domain or in the case of a CNAME record), for example, 76.76.21.21 or vercel.com.
• TTL (Time to live): The length of time the recursive server should keep a particular record in its cache. You should set this time based on how often people are visiting your site and how often your site may change. For more information, see the DNS propagation section.
• Record Type: For example, CNAME. There are many different types of records, some of the most common are listed below.

To learn more about adding, verifying, and removing DNS records, see "Managing DNS records".

When you're configuring or making changes to your DNS settings, you should be aware that it doesn't happen instantaneously. There's a whole network of servers, each of which has their own cache, and each of these will need to be updated to any new values that you set. For this reason, it can be normal to take up to 24-48 hours to see changes fully propagate through the network.

As we described earlier, when you set a record, you normally set a TTL value, or Time to Live, on a DNS record. This value, set in seconds, is the length of time a DNS cache will store information about your site, before it requests a new copy of the record from the authoritative server.

When you set the TTL value in your DNS record, you need to find the balance between serving your users the site quickly, and ensuring they're not seeing outdated information. A short TTL (minimum 30s) is beneficial if you are constantly updating the content, but will cause slower load times for your site. Using a longer TTL (max 86400 seconds, or 24 hours) means that records are cached for longer, so the site can load quickly for your users. Vercel defaults to 60s for a DNS record.

When you are transferring an existing (in-use) domain to Vercel, it's a good practice to check the existing DNS record and its TTL before switching. Ideally, about 24 hours in advance of changes, you should shorten the DNS TTL to 60s. Once it's propagated, you can then change the DNS record to Vercel so that traffic quickly moves over to the new site because now the DNS TTL is much shorter.

You can use tools such as https://www.whatsmydns.net to determine if your DNS settings have been fully propagated.

Nameservers are the actual servers on the network that are responsible for resolving domain names to the IP addresses where your site is hosted. Most domain registrars, including Vercel, provide their own nameservers. For Vercel these are:

• ns1.vercel-dns.com
• ns2.vercel-dns.com

When you purchase your domain through Vercel, we can set all the DNS records, including nameserver records, that tell anyone looking for your site where it can be found.

• Automatic DNS Records: Domains with nameservers pointed to Vercel don't need explicit DNS records created for the apex domain or first-level subdomains since they will be created automatically. This means that you can add a domain or subdomain to a project without thinking about DNS records at all. Not only does this reduce the potential for mistakes, but if you have multiple subdomains that you would like to use for your project, it takes away the need for manual entry of CNAME records for each of them.

• Wildcard Domains: When using Vercel's nameservers you can add wildcard domains without any further configuration.

• Custom nameservers: For domains registered with Vercel, you can add custom nameservers to your Vercel-hosted domain directly from the dashboard, allowing for delegation to other DNS providers. Add up to four nameservers at once, and revert to your previous settings if necessary.

For domains that are not registered with Vercel, you can change the nameservers directly from the domain registrar's dashboard.

An SSL certificate enables encrypted communication between user's browser and your web server to be encrypted. The certificate is installed on the web server and allows for website authentication and data encryption. This is particularly important if you are working with any sort of authentication and personal or financial data.

SSL certificates are issued from a certificate authority (CA) for each domain. While it is possible to create an upload your own custom certificate, Vercel will automatically try to generate a certificate for every domain once it is added to a project, regardless of if it was registered through Vercel or not. However, it will only work once the certificate validation request is successful, which happens once DNS records are added and propagated.

Vercel uses LetsEncrypt for certificates. For all non-wildcard domains, we use the HTTP-01 challenge method and providing the request can make it to Vercel, then our infrastructure will deal with it. For wildcard requests, we use the DNS-01 challenge method. This is why we require nameservers to be with Vercel to use wildcard domains - if the DNS isn't with us, we can't make the DNS record to approve it.

Issuing a certificate happens in the following way:

1. Vercel asks LetsEncrypt for a certificate for that domain and asks how it can prove control of the domain
2. Let's Encrypt reviews the domain and issues Vercel with a challenge in order to authorise the certificate to be generated. This is usually in the format of creating a file or DNS record with a particular code.
3. Vercel creates that file with the code on the HTTP-01 or DNS-01 validation path and tells LetsEncrypt it's done
4. LetsEncrypt then check to see if the file is there and if they can see the file, they send us the certificate
5. Vercel then adds the certificate to our infrastructure and it then starts working on HTTPS

For information about when SSL certificate renewals happen, see When is the SSL Certificate on my Vercel Domain renewed?