Custom Domain Setup

After deploying LinkDen, you can add a custom domain so your link page is accessible at yourdomain.com instead of the default *.workers.dev URL. This guide covers setup for both the web app and API Workers, with instructions for various DNS providers.

Overview

LinkDen has two Workers that can each get a custom domain:

You can set up a custom domain for one or both services.

Option 1: Domain on Cloudflare DNS (Recommended)

If your domain is already using Cloudflare's nameservers, the setup is nearly automatic and provides the best performance.

Add Your Domain to Cloudflare

If your domain is not yet on Cloudflare:

1. Go to the Cloudflare dashboard.
2. Click Add a site.
3. Enter your domain name and select the Free plan.
4. Cloudflare scans your existing DNS records.
5. Update your domain's nameservers at your registrar to the ones Cloudflare provides (e.g., ada.ns.cloudflare.com, bob.ns.cloudflare.com).
6. Wait for nameserver propagation (usually 15 minutes to 24 hours).

Set Up Custom Domains for Workers

For each Worker (linkden-web and linkden-api):

1. Go to Workers & Pages in the Cloudflare dashboard.
2. Click on the Worker.
3. Go to Settings > Domains & Routes.
4. Click Add Custom Domain.
5. Enter your domain (e.g., links.yourdomain.com for web, api.yourdomain.com for API).
6. Click Add Custom Domain.

Cloudflare automatically creates the DNS record and provisions an SSL certificate.

Update Environment Variables

After adding custom domains, update your environment variables:

apps/web/.env:

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

Worker environment variables (via dashboard or Wrangler):

CORS_ORIGIN=https://yourdomain.com
APP_URL=https://yourdomain.com

Redeploy for changes to take effect:

pnpm cf:deploy

Option 2: Domain on External DNS (Namecheap, GoDaddy, Route 53, etc.)

If your domain uses a DNS provider other than Cloudflare, you need to manually add DNS records.

Step 1: Add the Domain in Cloudflare

Follow the same steps as Option 1 to add the custom domain in the Cloudflare dashboard (Workers & Pages > your Worker > Settings > Domains & Routes). Cloudflare shows you the required DNS record.

Step 2: Add DNS Records at Your Provider

For the Web App (Pages)

Add a CNAME record at your DNS provider:

Replace linkden-web.your-subdomain.workers.dev with the actual Pages URL shown in the Cloudflare dashboard.

For the API (Worker)

Add a CNAME record for the API subdomain:

Provider-Specific Instructions

Namecheap

1. Log in to your Namecheap account.
2. Go to Domain List and click Manage next to your domain.
3. Go to the Advanced DNS tab.
4. Click Add New Record.
5. Select CNAME Record.
6. For the host, enter @ (apex) or your subdomain (e.g., links).
7. For the value, enter linkden-web.your-subdomain.workers.dev.
8. Set TTL to Automatic.
9. Click the checkmark to save.

Note: Namecheap does not support CNAME records on the apex domain (@). Use a subdomain or transfer your domain to Cloudflare.

GoDaddy

1. Log in to your GoDaddy account.
2. Go to My Products and click DNS next to your domain.
3. Click Add under the records table.
4. Select CNAME as the type.
5. Enter the host (@ for apex, or a subdomain like links).
6. Enter the target as linkden-web.your-subdomain.workers.dev.
7. Set TTL to 1 Hour.
8. Click Save.

Note: GoDaddy does not support CNAME on the apex domain. Use a subdomain or transfer to Cloudflare.

Amazon Route 53

1. Open the Route 53 console.
2. Go to Hosted zones and click on your domain.
3. Click Create record.
4. For the record name, enter a subdomain or leave blank for apex.
5. For record type, select CNAME.
6. Enter linkden-web.your-subdomain.workers.dev as the value.
7. Set TTL to 300.
8. Click Create records.

For apex domains, Route 53 supports ALIAS records: select record type A and toggle Alias on, but note this only works for AWS resources. For Cloudflare Pages, use a subdomain or transfer to Cloudflare DNS.

Cloudflare Registrar (Domain Not Yet Proxied)

If your domain is registered with Cloudflare but not yet using Cloudflare DNS:

1. Go to the Cloudflare dashboard.
2. Click Add a site and add your domain.
3. The DNS records are managed directly in Cloudflare -- follow the "Option 1" instructions above.

Step 3: Wait for DNS Propagation

DNS changes can take up to 48 hours to propagate globally, though most providers update within 5-30 minutes.

To check propagation status:

# Check CNAME resolution
dig yourdomain.com CNAME +short

# Check if the domain resolves
dig yourdomain.com A +short

# Or use nslookup
nslookup yourdomain.com

You can also use online tools:

• whatsmydns.net -- check DNS propagation worldwide
• dnschecker.org -- similar global DNS checker

Cloudflare shows the domain as "Active" in the dashboard once the CNAME is verified.

Step 4: SSL Certificate Provisioning

Cloudflare automatically provisions a free SSL certificate for your custom domain once DNS verification completes.

• For Cloudflare DNS domains: The certificate is issued instantly.
• For external DNS domains: The certificate is issued after the CNAME record is verified (typically within 15 minutes of DNS propagation).

No manual certificate management, renewal, or configuration is needed. Cloudflare handles the entire certificate lifecycle.

To verify SSL is active:

1. Visit https://yourdomain.com in your browser.
2. Click the lock icon in the address bar.
3. Verify the certificate is issued by Cloudflare.

Apex Domain Configuration

An apex domain (also called a root domain or naked domain) is yourdomain.com without any subdomain prefix.

Cloudflare DNS (Works Automatically)

If your domain uses Cloudflare DNS, apex domains work automatically. Cloudflare uses CNAME flattening to resolve CNAME records at the apex into A records, which is required by the DNS specification.

Simply add your apex domain as a custom domain for Pages, and Cloudflare handles the rest.

External DNS (Limitations)

Most external DNS providers do not support CNAME records on the apex domain because the DNS specification (RFC 1034) forbids CNAME records at the zone apex when other records exist (like SOA and NS).

Your options:

1. Transfer your domain to Cloudflare DNS (recommended): Cloudflare's registrar is free and supports CNAME flattening at the apex. This is the simplest solution.

2. Use a subdomain instead: Use links.yourdomain.com or www.yourdomain.com instead of the bare apex domain.

3. Check for ALIAS/ANAME support: Some providers offer proprietary record types that work like CNAME at the apex:

4. Set up a redirect: Configure a redirect from the apex domain to a www subdomain at your DNS provider, then point www via CNAME to Pages.

Setting Up Both Web and API on the Same Domain

You can run the web app and API on the same apex domain using different paths or subdomains:

Subdomain Approach (Recommended)

yourdomain.com       → Cloudflare Pages (web app)
api.yourdomain.com   → Cloudflare Worker (API)

This is the simplest and most maintainable configuration.

Path-Based Approach (Advanced)

Using Cloudflare Workers routes, you can route /api/* to the Worker and everything else to Pages. This requires additional Worker configuration and is not recommended for most users.

Verifying the Complete Setup

After configuring custom domains, run through this checklist:

1. Public page: Visit https://yourdomain.com -- you should see your link page.
2. HTTPS: The browser shows a lock icon (SSL is active).
3. Admin panel: Navigate to https://yourdomain.com/admin -- the Clerk sign-in page loads.
4. Authentication: Sign in successfully and reach the admin dashboard.
5. API connection: Create or edit a link in the admin panel -- the change saves without errors.
6. API domain: Visit https://api.yourdomain.com directly -- it should return a response (not a 404 or connection error).
7. Analytics: View the analytics page and confirm page view data is being recorded.

Removing a Custom Domain

To remove a custom domain:

1. Go to the Cloudflare dashboard.
2. Navigate to the Pages project or Worker.
3. Go to Custom Domains.
4. Click the three-dot menu next to the domain and select Remove.
5. Remove the corresponding CNAME record from your DNS provider.
6. Update your environment variables back to the default *.workers.dev / *.workers.dev URLs.
7. Redeploy.