Custom Domain & DNS Setup

Your Worker is running on *.workers.dev — but you want it on your own domain. This lesson covers two things: pointing a subdomain from your Google Workspace domain to Cloudflare, and attaching it to your Worker with automatic SSL.

The Two Approaches

There are two ways to use your domain with Cloudflare Workers:

For most people with a Google Workspace domain, the full setup is better — you get the complete security and speed layer for free. Google Workspace (Gmail, Calendar, Drive) will keep working because you'll add the required MX and CNAME records in Cloudflare's DNS.

Option A: Full Setup (Move Nameservers to Cloudflare)

This gives you the most value — your entire domain gets Cloudflare's DDoS protection, caching, and DNS performance.

Step 1: Add Your Domain to Cloudflare

1. Sign in to the Cloudflare dashboard
2. Click Add a site
3. Enter your domain (e.g., yourdomain.com)
4. Select the Free plan
5. Cloudflare will scan your existing DNS records and import them

Step 2: Verify Google Workspace Records

Make sure these records exist in Cloudflare's DNS after import:

Step 3: Change Nameservers at Your Registrar

Cloudflare will give you two nameservers (e.g., ada.ns.cloudflare.com and bob.ns.cloudflare.com). Update these at your domain registrar:

• Google Domains / Squarespace: My domains → DNS → Custom name servers
• Namecheap: Domain List → Manage → Nameservers → Custom DNS
• GoDaddy: Domain Settings → Nameservers → Change

Propagation takes anywhere from a few minutes to 48 hours (usually under 1 hour).

Step 4: Add a Subdomain for Your Worker

Once your domain is active in Cloudflare, you don't need to manually create DNS records for Worker subdomains. Custom Domains handle this automatically.

Option B: CNAME Setup (Keep Existing DNS)

If you don't want to move your nameservers (or can't), you can add a CNAME record for just your subdomain at your current DNS provider:

# At your current DNS provider (e.g., Google Domains):
Type:  CNAME
Name:  app              (this creates app.yourdomain.com)
Value: your-worker.your-account.workers.dev

Attaching Your Custom Domain to the Worker

Once your domain is in Cloudflare (Option A), connecting a subdomain to your Worker is one step:

Via Wrangler (recommended)

In your wrangler.jsonc:

{
  "name": "my-app",
  "main": "src/index.js",
  "routes": [
    {
      "pattern": "app.yourdomain.com",
      "custom_domain": true
    }
  ]
}

Then deploy:

npx wrangler deploy

That's it. Cloudflare will:

• Create the DNS record pointing app.yourdomain.com to your Worker
• Issue an SSL certificate automatically
• Enable DDoS protection on the subdomain
• Route all traffic on that subdomain to your Worker

Via Dashboard

1. Go to Workers & Pages → select your Worker
2. Settings → Domains & Routes → Add → Custom Domain
3. Enter app.yourdomain.com
4. Click Add Custom Domain

Updating Your OAuth Redirect URI

Now that your Worker has a custom domain, update your Google OAuth credentials:

1. Go to Google Cloud Console → Credentials
2. Edit your OAuth client
3. Add https://app.yourdomain.com/auth/callback to Authorized redirect URIs
4. Your OAuth Worker automatically picks up the new domain because it uses url.origin to construct the redirect URI

Restricting OAuth to Your Workspace Domain

If you only want users from your Google Workspace (e.g., @yourcompany.com) to sign in, add a check after fetching user info in your OAuth callback:

// In the /auth/callback handler, after fetching user info:
const user = await userRes.json();

// Restrict to your Google Workspace domain
if (!user.email.endsWith("@yourcompany.com")) {
  return new Response("Access denied. Must use @yourcompany.com account.", {
    status: 403,
  });
}

Alternatively, you can use Google's hd (hosted domain) parameter when constructing the auth URL to pre-filter the account picker:

const params = new URLSearchParams({
  client_id: env.GOOGLE_CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  response_type: "code",
  scope: "openid email profile",
  hd: "yourcompany.com",  // Only show Workspace accounts
});

The Complete Picture

What You Get for Free

• ✅ Custom domain (app.yourdomain.com) — via Custom Domains
• ✅ Automatic SSL certificate — issued by Cloudflare
• ✅ DDoS protection — unmetered, on the custom domain
• ✅ Google OAuth login — runs entirely at the edge
• ✅ Session management — stored in KV with auto-expiry
• ✅ Google Workspace email/calendar — unaffected (MX records preserved)