Deployment Overview

StarryBio is a static Astro project. Every supported provider starts from the same application build:

StarryBio source/config → pnpm build → portable dist/ → hosting-provider layer

pnpm build requires no hosting account or provider credentials. It validates the selected configuration module, generates configured assets and icons, and creates a complete static site in dist/. Provider selection happens after that build, except that the GitHub Pages workflow supplies its configured site URL and base path while it builds.

Supported providers

Provider	Provider file	Build command	Publish directory	Deployment guide
GitHub Pages	.github/workflows/deploy-github-pages.yml	pnpm build	dist Pages artifact	GitHub Pages
Cloudflare Workers	wrangler.jsonc	pnpm build	dist	Cloudflare
Vercel	vercel.json + Corepack build variable	pnpm build	dist	Vercel
Netlify	netlify.toml	pnpm build	dist	Netlify
Other static hosts	provider-specific	pnpm build	dist	Use the portability notes below.

No supported provider needs an Astro server adapter because StarryBio has no on-demand or server-rendered routes. Do not install @astrojs/vercel, @astrojs/netlify, or another server adapter unless a future source change genuinely adds server-side behavior.

Shared behavior

• src/pages/404.astro builds to dist/404.html. GitHub Pages, Vercel, and Netlify serve it for an unmatched static path; Cloudflare selects it through assets.not_found_handling.
• pnpm headers generates the Cloudflare/Netlify _headers policy and matching Vercel rules from the selected analytics configuration. pnpm build rejects stale generated headers.
• GitHub Pages deploys the static files but does not interpret _headers or vercel.json. Generated pages include compatible CSP directives, but full response-header coverage requires another host. See GitHub Pages.
• On root-hostname deployments, local assets and root-relative internal links use /. During a GitHub Pages build, actions/configure-pages supplies the actual Pages base path to Astro. This makes a project site such as https://USERNAME.github.io/REPOSITORY/ emit links and public assets below /REPOSITORY/, without changing Cloudflare, Vercel, Netlify, or ordinary root-hosted builds.
• Hashed Astro assets are cacheable as immutable on Cloudflare, Vercel, and Netlify. Authored /assets/* files use the shared cache rules on Cloudflare, Vercel, and Netlify. GitHub Pages controls its own response caching.
• .node-version pins Node.js 24 for reproducible remote builds. packageManager pins pnpm 12.3.4; pnpm-lock.yaml is the locked dependency graph.

The stock application has no runtime environment variables, secrets, functions, bindings, databases, or storage services. STARRYBIO_CONFIG_PATH is an optional non-secret build input for selecting a config module; it defaults to config/starrybio.config.ts. STARRYBIO_SITE_URL and STARRYBIO_BASE_PATH are workflow-only build inputs set from actions/configure-pages; users do not create or store them as secrets.

Add another static host

Build with pnpm build and publish the resulting dist/ directory at the hostname root. Configure the host to:

1. return 404.html with HTTP status 404 for unknown paths;
2. apply the security and cache intent from public/_headers using its native syntax, if it supports custom response headers;
3. use Node.js 24 and pnpm 12.3.4 for remote builds; and
4. rebuild whenever config/starrybio.config.ts, source code, or public assets change.

This works for a plain static server, object storage/CDN, or a future Docker/self-hosted target without adding provider checks to application components. A platform such as Railway, Render, or Fly.io may need a thin static web-server/container layer, but it should still serve the unchanged dist/ artifact.

Local verification

pnpm install
pnpm build
pnpm preview

pnpm preview uses Astro and verifies the normal root-hosted build. Use pnpm preview:cloudflare to verify Cloudflare’s _headers and custom-404 handling specifically. The GitHub Pages guide includes the separate project-site build check. Local verification does not prove that a remote account, custom domain, or production CDN is configured correctly; follow the chosen provider guide for those checks.