Custom Domains & SSL

How Domains Work on Vercel

When you add a custom domain, Vercel:

1. Verifies you own the domain (via DNS)
2. Provisions an SSL certificate (free, automatic)
3. Routes traffic to your deployment
4. Renews certificates automatically

User types: example.com
        ↓
DNS: example.com → Vercel's servers
        ↓
Vercel: Routes to your project
        ↓
User sees: Your app (with HTTPS!)

Adding a Domain

Via Dashboard

1. Go to your project in Vercel
2. Click Settings → Domains
3. Enter your domain (e.g., example.com)
4. Click Add
5. Follow the DNS configuration instructions

Via CLI

bash
Copy
# Add domain to current project
vercel domains add example.com

# Add domain to specific project
vercel domains add example.com --scope your-team

DNS Configuration

After adding a domain, configure your DNS. You have two options:

Option A: Using Vercel Nameservers (Recommended)

Transfer DNS management to Vercel for the simplest setup.

At your registrar, change nameservers to:

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

Benefits:

• Vercel manages all DNS records
• Automatic configuration
• Easy subdomain management
• Fastest propagation

Option B: Keep Existing DNS

Add these records at your current DNS provider:

For root domain (example.com):

Type: A
Name: @
Value: 76.76.21.21

For www subdomain:

Type: CNAME
Name: www
Value: cname.vercel-dns.com.

Domain Verification

After adding DNS records, Vercel verifies ownership:

Status: Pending Verification
   ↓ (DNS propagates)
Status: Valid Configuration
   ↓ (SSL provisioning)
Status: Valid ✓

Check Status

bash
Copy
vercel domains inspect example.com

# Output:
# Domain: example.com
# Status: Valid
# SSL: Active (auto-renewing)
# Nameservers: Vercel

DNS Propagation

DNS changes can take up to 48 hours, but usually complete within minutes to hours.

Check propagation:

• dnschecker.org
• whatsmydns.net

bash
Copy
# Check locally
dig example.com A

# Should return 76.76.21.21

Common Domain Configurations

Root + WWW (Most Common)

example.com      → Your app
www.example.com  → Redirects to example.com

Setup in Vercel:

1. Add example.com (primary)
2. Add www.example.com (redirects automatically)

WWW as Primary

www.example.com  → Your app
example.com      → Redirects to www.example.com

Setup:

1. Add www.example.com (primary)
2. Add example.com (set to redirect)

Subdomain Only

app.example.com  → Your app

Setup:

1. Add app.example.com
2. Configure CNAME: app → cname.vercel-dns.com

Subdomains

Adding Subdomains

bash
Copy
# Add subdomain
vercel domains add blog.example.com
vercel domains add api.example.com
vercel domains add staging.example.com

Wildcard Subdomains

For dynamic subdomains (e.g., tenant.example.com):

bash
Copy
vercel domains add "*.example.com"

In your app, read the subdomain:

javascript
Copy
// Next.js middleware
export function middleware(request) {
  const host = request.headers.get('host');
  const subdomain = host.split('.')[0];

  // Use subdomain for routing, tenant identification, etc.
}

Multiple Domains

Point multiple domains to the same project:

bash
Copy
vercel domains add example.com
vercel domains add example.org
vercel domains add myapp.io

One domain is "primary" (canonical), others redirect or serve directly.

Setting Primary Domain

In Dashboard: Settings → Domains → Click ⋯ → Set as Primary

The primary domain is used in:

• Canonical URLs
• Sitemap generation
• SEO-related headers

SSL Certificates

Automatic SSL

Vercel automatically:

• Provisions certificates (Let's Encrypt)
• Installs them on your domain
• Renews before expiration (every 90 days)

You don't need to do anything!

Force HTTPS

All traffic is automatically redirected to HTTPS. No configuration needed.

Custom Certificates (Enterprise)

Enterprise plans can upload custom SSL certificates for specific compliance requirements.

Redirects

Domain Redirects

When you add multiple domains, configure how they behave:

In vercel.json

json
Copy
{
  "redirects": [
    {
      "source": "/:path*",
      "has": [{ "type": "host", "value": "old-domain.com" }],
      "destination": "https://new-domain.com/:path*",
      "permanent": true
    }
  ]
}

Troubleshooting

"Invalid Configuration"

Usually means DNS records aren't correct.

bash
Copy
# Check DNS
dig example.com A
# Should return: 76.76.21.21

dig www.example.com CNAME
# Should return: cname.vercel-dns.com

"Pending Verification"

1. Wait for DNS propagation (up to 48 hours)
2. Verify DNS records are correct
3. Clear DNS cache: sudo dscacheutil -flushcache (macOS)

SSL Certificate Error

Usually resolves automatically. If persistent:

1. Remove the domain
2. Wait 5 minutes
3. Add it again

"Domain Already In Use"

The domain is assigned to another Vercel project.

1. Find which project has it (check all teams)
2. Remove from that project first
3. Add to your project

Mixed Content Warnings

Your app loads HTTP resources on HTTPS pages.

javascript
Copy
// Bad
<img src="http://example.com/image.png" />

// Good
<img src="https://example.com/image.png" />

// Better (protocol-relative)
<img src="//example.com/image.png" />

// Best (relative)
<img src="/image.png" />

Domain Management

List Domains

bash
Copy
vercel domains ls

# Output:
# ┌──────────────────────┬─────────┬───────────────┐
# │ Domain               │ Status  │ Added         │
# ├──────────────────────┼─────────┼───────────────┤
# │ example.com          │ Valid   │ 7 days ago    │
# │ www.example.com      │ Valid   │ 7 days ago    │
# │ staging.example.com  │ Valid   │ 2 days ago    │
# └──────────────────────┴─────────┴───────────────┘

Remove Domain

bash
Copy
vercel domains rm example.com

Transfer Domain (Between Projects)

1. Remove from old project
2. Add to new project
3. DNS remains the same

Registrar-Specific Instructions

GoDaddy

1. Go to Domain Settings → DNS Management
2. Change nameservers to Vercel, OR
3. Add A record: @ → 76.76.21.21
4. Add CNAME: www → cname.vercel-dns.com

Namecheap

1. Go to Domain List → Manage → Advanced DNS
2. Add A record: @ → 76.76.21.21
3. Add CNAME: www → cname.vercel-dns.com

Cloudflare

1. DNS → Add Record
2. A record: @ → 76.76.21.21 (Proxy OFF/DNS only)
3. CNAME: www → cname.vercel-dns.com (Proxy OFF)

Google Domains / Squarespace

1. DNS → Manage custom records
2. Add A: @ → 76.76.21.21
3. Add CNAME: www → cname.vercel-dns.com