Domains and DNS

StarryBio can use the default hostname supplied by GitHub Pages, Cloudflare Workers, Vercel, or Netlify for initial testing, then attach a root domain or subdomain for the public site. Domain and TLS setup belongs to the selected hosting provider; the static application itself remains unchanged.

Choose the public URL first

Before sharing the site, decide whether your canonical public address is a root domain such as example.com or a subdomain such as links.example.com. Put exactly that HTTPS URL in the site configuration:

seo: {
  canonicalUrl: 'https://links.example.com',
  image: '/og.png',
},
qr: {
  enabled: true,
  url: 'https://links.example.com',
},

This avoids social metadata, generated QR codes, and links referring to a temporary provider hostname after a custom domain is ready. See SEO and Analytics and Assets and Generated Downloads.

GitHub Pages domains

For a GitHub Pages project site, the default canonical URL must include the repository path, for example https://USERNAME.github.io/REPOSITORY/. A user or organization site named USERNAME.github.io or ORGANIZATION.github.io has no repository path. StarryBio’s GitHub Actions workflow reads the Pages configuration and builds the matching Astro base path automatically.

To use a custom domain, set it first in Settings > Pages > Custom domain, then create the DNS record GitHub requests. Use an account-host CNAME target such as USERNAME.github.io, not a URL containing the repository name. GitHub’s custom workflow ignores CNAME files, so do not add one under public/. When GitHub has verified the DNS record, enable Enforce HTTPS and push the canonical-URL update. The detailed GitHub Pages guide includes exact project/user-site URL rules and DNS values.

Vercel and Netlify domains

For Vercel, add the hostname under the project’s Settings > Domains and follow the project-specific DNS records Vercel displays. For Netlify, choose Domain management > Add a domain > Add a domain you already own, then choose Netlify DNS or an external DNS provider. Both providers provision HTTPS after DNS validation. Configure root/www or old/new-host redirects in the selected provider, then redeploy after updating seo.canonicalUrl.

See Deploying to Vercel or Deploying to Netlify for the complete workflow. The Cloudflare-specific options below apply only when Cloudflare Workers is the selected host.

Use the workers.dev URL for initial testing

The repository does not set workers_dev in wrangler.jsonc, so Cloudflare’s Worker default applies. After pnpm deploy, Wrangler reports the address if the account’s workers.dev subdomain is enabled.

Use it to verify a first deployment, but prefer a custom domain or Worker route for a production site. The workers.dev name is tied to the Worker name in wrangler.jsonc and your account’s Workers subdomain. Changing the Worker name creates a different address.

If you do not want the temporary address publicly reachable after your domain is live, manage it in the Worker’s Cloudflare dashboard settings and make sure any workers_dev setting you later add to wrangler.jsonc agrees with that choice. A dashboard-only disable can be re-enabled by a later Wrangler deployment if the configuration tells it to enable the route.

Add a Cloudflare Custom Domain in the dashboard

This is the recommended path for one StarryBio hostname because it does not require changing the stock Worker configuration.

Before you begin:

1. Add the domain to Cloudflare and make sure its zone is active.
2. Make sure Cloudflare manages the zone’s nameservers; Workers custom domains cannot attach to a zone whose nameservers are managed elsewhere.
3. Pick a hostname that has no conflicting CNAME record. Cloudflare Custom Domain setup creates the necessary DNS record and certificate.

Then:

1. Deploy StarryBio with pnpm deploy.
2. In the Cloudflare dashboard, open Workers & Pages, select the Worker, then open Settings > Domains & Routes (or the current Domains view).
3. Choose Add > Custom Domain.
4. Enter the root domain or subdomain, such as links.example.com, and confirm.
5. Wait for Cloudflare to create the DNS record and issue TLS certificates.
6. Open https://links.example.com and confirm the homepage, an asset URL, and an unknown route.

A Custom Domain sends every path on the attached hostname to this Worker. It is best for StarryBio when the hostname has no separate origin server that must receive requests.

Configure a custom domain in wrangler.jsonc

Use this only if you want domain configuration reviewed and deployed with the source:

{
  "routes": [
    {
      "pattern": "links.example.com",
      "custom_domain": true,
    },
  ],
}

Deploy the changed configuration:

pnpm deploy

The same prerequisites apply: active Cloudflare zone, Cloudflare-managed nameservers, and no conflicting CNAME. Do not leave an old links.example.com/* Worker route attached while migrating that hostname to a Custom Domain.

Use a Worker route when another origin must remain

A normal Worker route is different from a Custom Domain. It matches a path pattern in an existing Cloudflare zone and requires a DNS record for the hostname first. For example:

{
  "routes": [
    {
      "pattern": "example.com/links/*",
      "zone_name": "example.com",
    },
  ],
}

StarryBio’s built static assets are normally rooted at /. The GitHub Pages workflow is the supported exception: it receives the Pages base path and builds a project-site artifact below /REPOSITORY/. A Cloudflare Worker route under a path prefix still requires its own matching routing/build design, so prefer a dedicated subdomain such as links.example.com instead of treating that Pages behavior as a general Worker route solution.

TLS, redirects, and canonicalization

Every supported provider can provision and manage TLS certificates; load the site with https:// after setup completes. StarryBio does not itself create redirects between:

• www.example.com and example.com
• an old domain and a new domain
• a provider preview/default hostname and your custom domain

Choose one canonical URL in seo.canonicalUrl. If you attach more than one hostname, add a redirect through the selected provider so visitors and search engines land on that canonical hostname. Do not expect the static page to perform hostname redirects.

Domain verification checklist

1. https://<canonical-host>/ returns the correct site and a valid certificate.
2. https://<canonical-host>/does-not-exist returns the custom StarryBio 404 page.
3. Local assets and generated qr.png/contact.vcf files load and download when enabled. On a GitHub Pages project site, their URL starts with /REPOSITORY/; on a root or custom-domain deployment, it starts with /.
4. Page source contains the intended canonical and Open Graph URL values.
5. If another hostname is used, it redirects to the canonical URL rather than serving duplicate content.

If the dashboard cannot add the domain or the domain serves another application, see Troubleshooting. Cloudflare’s current Custom Domains documentation and Workers routing documentation provide platform-specific details beyond StarryBio’s configuration.