Static Site Generators in Production

Custom Domains and TLS on Cloudflare Pages

Every Cloudflare Pages project gets a *.pages.dev address with a valid certificate the moment it is created. Putting the site on your own domain adds two pieces: a DNS record that routes the name to the project, and a certificate for that name issued and renewed automatically. When both zones and records are on Cloudflare, it takes a minute. When they are not — or when an old record, a CAA policy or a redirect loop gets in the way — it becomes the most confusing part of the deploy.

This guide covers attaching apex and www domains, how certificates are issued, which SSL settings matter for a static site, HTTPS enforcement, and the fixes for the failures people hit most. It is part of Cloudflare Pages Edge Caching Setup.

Prerequisites

  • A Pages project with at least one successful deployment.
  • Control of the domain's DNS, ideally as a zone in the same Cloudflare account.
  • Knowledge of any existing records for the names you are about to use.

Zone on Cloudflare or Not

The setup depends on where the domain's DNS lives.

Custom domain setup depending on where DNS is hosted If the zone is on Cloudflare, adding the domain in Pages creates a proxied CNAME automatically, supports apex domains through CNAME flattening, and issues the certificate in minutes. If DNS is elsewhere, you create a CNAME to the pages.dev hostname yourself, apex domains are not supported, and validation takes longer. Two setup paths Zone on Cloudflare record created for you (proxied CNAME) apex works via CNAME flattening certificate in a few minutes zone features apply: rules, WAF, cache rules, analytics recommended DNS elsewhere you add CNAME → project.pages.dev subdomains only, no apex validation can take hours zone-level rules unavailable for this hostname works for docs.example.com
Moving the zone to Cloudflare is the simplest way to use an apex domain on Pages.

Zone on Cloudflare. In the Pages project, open Custom domains, choose Set up a custom domain and enter the name. Pages creates a proxied CNAME to project.pages.dev — flattened at the apex — and requests a certificate. Nothing else is needed.

DNS elsewhere. Add a CNAME at your DNS provider from the subdomain to project.pages.dev, then add the domain in the Pages dashboard. Pages validates the record and issues a certificate. Apex domains cannot be attached this way because most providers cannot put a CNAME at the apex.

Apex and www Together

Most sites want both example.com and www.example.com to work, with one redirecting to the other. Attach both names to the Pages project, then add one redirect so readers and search engines see a single canonical host. A zone-level Redirect Rule is the cleanest place for it:

When incoming requests match:  Hostname equals "www.example.com"
Then:  Dynamic redirect to  concat("https://example.com", http.request.uri.path)
       Status 301, preserve query string

A _redirects rule cannot do this, because its sources are paths, not hostnames. Make sure the canonical host matches what the site generator uses for canonical URLs and sitemaps — a mismatch sends search engines conflicting signals. Redirect options in detail are in Configuring Redirects on Cloudflare Pages.

How the Certificate Is Issued

Pages requests a certificate for each custom domain from one of the certificate authorities Cloudflare uses, validates control of the name through the DNS record, and renews it automatically before expiry. You never upload or rotate anything.

Two things can stop issuance:

  • CAA records. A CAA record restricts which authorities may issue for the domain. If the zone has one that allows only a single authority, Pages cannot get a certificate from the others. Add CAA entries for the authorities Cloudflare lists in its documentation, or remove the restriction.
  • Conflicting records. An existing A or AAAA record for the same name, left over from a previous host, takes precedence or confuses validation. Delete it before adding the domain.

A third, rarer cause is DNSSEC left enabled at the registrar with keys from a previous DNS provider after moving the zone; resolvers then reject every answer for the domain. Check that the DS record at the registrar matches the one Cloudflare shows, or remove it and re-enable DNSSEC from Cloudflare.

The dashboard shows the domain's status as it moves from "Verifying" to "Active". If it stays in verification for more than 15 minutes with the zone on Cloudflare, one of the two causes above is almost always responsible.

Diagnosing a custom domain stuck in verification A checklist flow. First check for an old A or AAAA record on the name and delete it. Then check CAA records allow Cloudflare's certificate authorities. Then, for external DNS, confirm the CNAME points to the exact pages.dev hostname. Finally retry validation from the dashboard. Stuck on "Verifying": check in this order 1. Old records A / AAAA / CNAME on the same name 2. CAA policy allows Cloudflare's authorities? 3. CNAME target exact project .pages.dev name 4. Retry re-check from the dashboard dig +short CAA example.com · dig +short docs.example.com causes 1 and 2 account for nearly every stuck domain on a Cloudflare-hosted zone
Two dig commands usually reveal the problem before you open a support ticket.

SSL Settings That Matter

The zone's SSL/TLS encryption mode (Off, Flexible, Full, Full (strict)) controls how Cloudflare connects to an origin server. Pages is served by Cloudflare itself, so the mode does not change how the Pages site is served, but it does affect every other proxied record in the zone. Set it to Full (strict) so no other hostname silently falls back to unencrypted origin connections.

Then enforce HTTPS for readers:

  • Always Use HTTPS redirects every http:// request to https:// at the edge.
  • HSTS tells browsers to use HTTPS for the domain for a set period without trying HTTP first. Enable it with a short max-age first, confirm nothing breaks, then raise it; see Enabling HSTS and Preload Safely.
  • Minimum TLS version of 1.2 is a safe default. TLS 1.3 is enabled automatically.

You can also set HSTS in _headers for the Pages project, which keeps it versioned with the site. Setting it in both places is harmless as long as the values match.

How a first and a repeat visit reach the canonical HTTPS URL On a first visit, http://www.example.com is redirected by Always Use HTTPS to https://www, then by the Redirect Rule to https://example.com, which returns an HSTS header. On a repeat visit, the browser upgrades to HTTPS internally because of HSTS, so only the www redirect remains. Reaching https://example.com/ First visit http://www.example… https://www.example… https://example.com/ Always Use HTTPS Redirect Rule Repeat visit (HSTS cached) https://www.example… https://example.com/ browser upgrades internally link to the canonical host everywhere so most readers need no redirect at all
HSTS removes the HTTP hop on repeat visits; consistent links remove the host hop.

The redirect chain on a first visit is short, but it is still two round trips before the page begins to load. Keep every internal link, sitemap entry and canonical tag on the final https:// canonical host, and list that host in any marketing or social profiles, so most visitors arrive without any redirect at all.

Keeping pages.dev Out of Search Results

The project's *.pages.dev address keeps working after you attach a custom domain, and it serves the same content. If search engines discover it, they may index duplicates. Two options:

  1. Add a _headers rule that sends X-Robots-Tag: noindex on the pages.dev host only — _headers supports host-specific rules with a full URL as the path, for example https://project.pages.dev/*.
  2. Add a Redirect Rule in a Cloudflare Access or Worker layer that redirects pages.dev requests to the canonical domain.

Both keep preview URLs usable for reviewers. The first is simpler and does not affect branch previews on *.project.pages.dev, which should also carry noindex.

Measured Impact

A company moved its developer documentation from a self-managed Nginx server with manually renewed certificates to Cloudflare Pages with an apex custom domain. Certificate-related incidents, which had happened twice in the previous year when renewals failed, dropped to zero. The www redirect moved from an Nginx config to a single Redirect Rule, the pages.dev host was marked noindex, and a site audit two months later found no duplicate-host URLs indexed.

Pitfalls & Rollback

  • Flexible SSL mode. It connects to origins over HTTP; for any non-Pages record in the zone, that means unencrypted traffic and potential redirect loops.
  • Apex with external DNS. Not supported; move the zone or use a subdomain.
  • HSTS preload too early. Preloading is hard to undo; wait until every subdomain serves HTTPS.
  • Deleting the domain from Pages to "retry". It also removes the DNS record; note the record first.
  • Rollback: remove the custom domain from the project and restore the previous DNS record; the site remains on pages.dev.

Conclusion

On Cloudflare Pages, custom domains and TLS are automatic when the zone is on Cloudflare: add the name, Pages creates the record and certificate, and renewals take care of themselves. Attach both apex and www with a Redirect Rule to one canonical host, set the zone to Full (strict) with Always Use HTTPS and HSTS, keep pages.dev out of search results, and check old records and CAA policies first whenever a domain gets stuck.

FAQ

Can I use an apex domain with Cloudflare Pages?

Yes, if the domain's DNS zone is on Cloudflare. Pages creates a flattened CNAME at the apex pointing to the project. If the domain uses another DNS provider, only subdomains can be attached, via a CNAME record you create at that provider.

How long does certificate issuance take for a Pages custom domain?

Usually a few minutes when the zone is on Cloudflare. For external DNS it can take longer because the certificate authority must validate the CNAME, and a CAA record that does not allow Cloudflare's certificate authorities will block issuance entirely.

Which SSL/TLS mode should I use for a Pages site?

The zone SSL mode affects traffic between Cloudflare and origins, and Pages is served by Cloudflare itself, so the mode matters mostly for other records in the zone. Use Full (strict) for the zone and enable Always Use HTTPS and HSTS for the site.

Why does my custom domain show a 522 or certificate error after setup?

Usually because an old DNS record for the same name still points elsewhere, or because a CAA record blocks issuance. Delete conflicting A, AAAA or CNAME records, check CAA records, and re-trigger validation from the Pages dashboard.