Deploying to Netlify

StarryBio deploys to Netlify as a static Astro site. The committed netlify.toml runs the canonical production build and publishes dist/; Netlify reads the resulting dist/_headers file for the shared security and cache policy. No Netlify CLI, Astro adapter, Function, or runtime service is needed.

Prerequisites

• A configured StarryBio repository on a Git provider connected to Netlify.
• A Netlify account with permission to create a project.
• Your content changes committed in config/starrybio.config.ts and any local assets in public/.

The repository root contains .node-version with 24, packageManager: "pnpm@12.3.4", and pnpm-lock.yaml. Netlify uses the base-directory .node-version before a UI Node selection and recognizes pnpm-lock.yaml; Corepack uses the exact pnpm version declared by packageManager. The stock site has no application build-time or runtime environment variables. Do not set NODE_ENV=production: Netlify would omit the development dependencies needed to run Astro and the build scripts.

The README Deploy to Netlify button is only a shortcut to Netlify’s repository-import flow. It does not publish a prebuilt dist/ folder or replace source control. Fork or create your own repository first when you want to keep configuration changes.

Import and deploy

1. Push the configured repository to your Git provider.

2. In Netlify, open the team’s Projects page, choose Add new project > Import an existing project, choose the Git provider, and select the repository.

3. Keep the Base directory empty so Netlify builds from the repository root. Confirm the configuration before deploying:

   Setting	Exact value
   Base directory	repository root (empty)
   Build command	pnpm build
   Publish directory	dist
   Node.js	24 from .node-version
   Package manager	pnpm 12.3.4 from packageManager
   Application environment variables	none

   The committed netlify.toml is authoritative for the build command and publish directory; current Netlify file-based configuration takes precedence over the corresponding dashboard values. Edit the committed file if this project’s build contract changes, rather than relying on an uncommitted dashboard setting.

4. Select Deploy. Open the assigned *.netlify.app production URL when the build completes.

5. Check the homepage, a local asset, a deliberately unknown path, every enabled generated download, and the browser console.

Astro emits dist/404.html; Netlify uses that static page for unmatched paths without an SPA redirect. Astro copies public/_headers to dist/_headers, which Netlify applies as the CSP, browser-security headers, and cache rules. Do not add a catch-all rewrite to index.html: it would hide the custom 404 page.

Continuous deployment and updates

The production branch selected during import (normally main) deploys each new push. On supported Git workflows, pull requests receive Deploy Previews; they are previews, not the production URL.

For a routine StarryBio update:

1. Edit config/starrybio.config.ts, public/, or source files.
2. Run pnpm validate, pnpm build, and pnpm preview locally when possible.
3. Commit and push the change to the production branch.
4. Review the Netlify build log and test the new production deploy.

A dashboard rebuild is useful only when the source revision is already correct. It cannot incorporate uncommitted local configuration. If a build uses the wrong directory or package manager, first confirm that the connected repository is the intended one and that its root contains netlify.toml, .node-version, package.json, and pnpm-lock.yaml.

Custom domain

1. Open the Netlify project and choose Domain management in the left sidebar.
2. Choose Add a domain > Add a domain you already own.
3. Enter the exact hostname, such as links.example.com or example.com, then follow the prompt to use Netlify DNS or an External DNS Provider.
4. If DNS stays with another provider, open Domain management > Production domains, select Pending DNS verification beside the domain, and use the record values Netlify displays. Do not guess or copy a record from a different project.
5. After Netlify reports that the domain is active and HTTPS is ready, update seo.canonicalUrl and qr.url to the exact https:// canonical URL, commit, and push.

Choose one primary hostname and configure any www/apex or old-domain redirect in Netlify’s domain controls. StarryBio is a static site; it does not perform host redirects in application code.

Troubleshooting

Netlify runs npm, the wrong Node version, or cannot find dist

Confirm the repository root is the Base directory and that the committed pnpm-lock.yaml, package.json, .node-version, and netlify.toml are present in it. Netlify detects pnpm from the lockfile, .node-version overrides its Node UI setting, and netlify.toml supplies pnpm build and dist.

Netlify shows a home page for a bad URL

Remove any SPA catch-all redirect. Keep src/pages/404.astro, verify pnpm build emits dist/404.html, and deploy the new build.

Headers or CSP are missing

Confirm the build output contains dist/_headers. Netlify reads that file only from the published output; a _headers file outside dist/ is not deployed. Run pnpm headers after changing analytics, as described in Security and Privacy.

For current provider details, consult Netlify’s project import guide, Astro build settings, dependency management, file-based configuration, and custom-domain guide. Astro’s general deployment guide confirms the static dist output contract.