How to Connect a Custom Domain to Vercel (The Definitive Step-by-Step Guide)

When you deploy a new web project on Vercel, it is assigned an automatic staging domain formatted as your-project-name.vercel.app. While this URL is ideal for internal QA testing, staging environments, and client previews, launching a real commercial brand or portfolio requires a clean, branded custom domain (e.g., yourdomain.com).

Connecting a custom domain to Vercel is straightforward, but improper DNS record configurations, trailing slash misalignments, or proxy conflicts (especially with Cloudflare) can cause confusing SSL handshake errors and downtime.

In this definitive guide, we walk through the exact end-to-end process of attaching both apex domains and subdomains to Vercel, configuring DNS records across major registrars, handling automated SSL generation, and resolving common connection pitfalls.

1. Domain Terminology Primer: Apex vs. Subdomain

Before opening your DNS settings, understand the two primary domain structures:

• Apex Domain (Root Domain / Naked Domain): This is your domain without any subdomain prefix, such as example.com.
• Subdomain: A prefix attached before your root domain, such as www.example.com, app.example.com, or blog.example.com.

The Canonical Decision: WWW vs. Non-WWW

Decide upfront which version will be your primary canonical URL.

• Option A (Apex First): Users visiting www.example.com are automatically redirected to example.com.
• Option B (WWW First): Users visiting example.com are redirected to www.example.com.

WebWise Recommendation: For large-scale applications, the WWW-first or CNAME-capable apex architecture is technically superior because DNS standards (RFC 1034) prohibit setting a standard CNAME record on an apex domain. Using www allows you to leverage Vercel's global Anycast CDN via a CNAME record without DNS flattening restrictions. Vercel handles automated 301 redirects seamlessly between whichever pair you choose.

2. Step 1: Adding the Domain to Your Vercel Project

1. Log into your Vercel Dashboard.
2. Select the project you wish to connect.
3. Click on the Settings tab in the top navigation bar.
4. In the left-hand sidebar, select Domains.
5. In the input field, enter your domain name. For a complete setup, enter your root domain: yourdomain.com.
6. Click Add.
7. Vercel will prompt you with a configuration recommendation:
   • "Add yourdomain.com and redirect www.yourdomain.com to it" OR
   • "Add www.yourdomain.com and redirect yourdomain.com to it"
8. Select your preferred canonical structure and click Add.

Vercel will now display a configuration status card showing an orange warning indicator: "Invalid Configuration". This is completely normal because your domain registrar has not yet been instructed to point to Vercel's servers.

3. Step 2: Configuring DNS Records at Your Registrar

Now open a new browser tab and log into where you purchased your domain (e.g., Cloudflare, Namecheap, GoDaddy, Google Cloud Domains, or Porkbun). Locate the DNS Management or DNS Records dashboard.

You have two primary configuration methods: A Records (Apex) and CNAME Records (Subdomains).

Method A: Configuring the Apex Domain (yourdomain.com)

Because the DNS specification forbids standard CNAME records on the apex root, you must point the root domain to Vercel's Anycast IP address using an A Record:

| Record Type | Host / Name | Value / Destination | TTL | |---|---|---|---| | A | @ (or blank) | 76.76.21.21 | Automatic (or 300s) |

Note: 76.76.21.21 is Vercel's globally distributed Anycast edge routing IP address.

Method B: Configuring the Subdomain (www.yourdomain.com)

For the www subdomain (or any other subdomain like docs or blog), create a CNAME Record:

| Record Type | Host / Name | Value / Destination | TTL | |---|---|---|---| | CNAME | www | cname.vercel-dns.com | Automatic (or 300s) |

4. Special Case: Configuring with Cloudflare DNS

If your domain's nameservers point to Cloudflare, you must pay close attention to Cloudflare's proxy mode.

Cloudflare offers two states for DNS records:

1. Proxied (Orange Cloud): Traffic routes through Cloudflare's edge proxy before reaching Vercel.
2. DNS Only (Grey Cloud): Traffic routes directly to Vercel.

The Recommended Setup:

If you want Vercel to manage your Let's Encrypt SSL certificates automatically and take advantage of Vercel Edge Middleware:

• Change the proxy status on both the A and CNAME records to DNS Only (Grey Cloud) during the initial domain verification.
• Once Vercel shows a green checkmark indicating successful SSL provisioning, you can re-enable Cloudflare's Orange Cloud proxy if you require Cloudflare's WAF or DDoS rules.
• Critical Cloudflare Setting: If you keep Cloudflare's proxy enabled (Orange Cloud), you must set your Cloudflare SSL/TLS encryption mode to Full (Strict). If you leave it on "Flexible", your visitors will encounter an infinite ERR_TOO_MANY_REDIRECTS redirect loop.

5. Step 3: Verifying Domain Status in Vercel

Return to your Vercel Domains dashboard.

1. Click the Refresh button next to your domain.
2. Vercel's background daemon will query public DNS resolvers (Google 8.8.8.8 and Cloudflare 1.1.1.1).
3. As soon as the records propagate, the status will switch from "Invalid Configuration" to a green "Valid Configuration" badge.

Automated SSL Certificate Generation:

Immediately upon DNS confirmation, Vercel initiates an automated certificate issuance request to Let's Encrypt.

• This process typically takes between 30 and 120 seconds.
• You do not need to install certbot, manage cron jobs, or upload private keys. Vercel automatically renews these TLS certificates 30 days prior to expiration without any human intervention.

6. How to Verify DNS Propagation via Terminal

You do not have to wait blindly in the dark wondering if your DNS records have updated. Use standard terminal utilities like dig or nslookup:

Check your A Record:

dig yourdomain.com +short

Expected Output:

76.76.21.21

Check your CNAME Record:

dig www.yourdomain.com +short

Expected Output:

cname.vercel-dns.com.
76.76.21.21

If dig returns empty lines or points to your registrar's old parking IP address (such as 198.54.x.x), your local DNS cache has not yet refreshed. Flush your local DNS cache:

• macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
• Windows: ipconfig /flushdns

7. Troubleshooting Common Connection Errors

| Symptom / Error | Root Cause | Immediate Solution | |---|---|---| | Conflicting DNS Records | You have an existing A or AAAA record from your old hosting provider competing with Vercel. | Delete all other A and AAAA records for the root host @. Only keep 76.76.21.21. | | CAA Record Restrictions | Your registrar has a Certificate Authority Authorization (CAA) record blocking Let's Encrypt. | Add a CAA record allowing letsencrypt.org to issue certificates for your domain. | | ERR_TOO_MANY_REDIRECTS | Cloudflare SSL mode is set to "Flexible", creating an encryption downgrade loop. | In Cloudflare SSL/TLS settings, switch mode from "Flexible" to Full (Strict). | | Domain Ownership Conflict | Another Vercel user previously claimed this domain on an inactive team account. | Vercel will ask you to add a temporary _vercel TXT verification record to prove DNS control. |

With your domain connected, verified, and SSL-encrypted, your web application is primed for global production traffic backed by Vercel's worldwide edge network.