Deploying to Vercel

StarryBio deploys to Vercel as a static Astro site. The committed vercel.json declares Astro, installs the locked pnpm dependencies, runs the canonical build, serves dist/, and applies Vercel’s equivalent of the shared security/cache headers. No Vercel CLI, Astro adapter, Function, or runtime service is required.

Prerequisites

• A configured StarryBio repository on GitHub, GitLab, Bitbucket, or Azure DevOps connected to Vercel.
• A Vercel account with permission to create a project.
• Your StarryBio content changes committed in config/starrybio.config.ts and local assets in public/.

The project’s engines.node accepts Node.js 24.x (or 26.0.0+), and its packageManager field pins pnpm 12.3.4. For this repository, Vercel runs Node.js 24 and the exact commands in vercel.json.

StarryBio needs one non-secret Vercel build variable because pnpm 12 is newer than Vercel’s automatically selected pnpm versions:

Environment variable	Exact value	Apply to
ENABLE_EXPERIMENTAL_COREPACK	1	Production, Preview, Development

This enables Vercel’s documented Corepack path, which reads packageManager: "pnpm@12.3.4" instead of choosing an older pnpm from the lockfile format. The stock site needs no application secrets or other environment variables.

The README Deploy with Vercel button opens Vercel’s repository-import flow and pre-fills ENABLE_EXPERIMENTAL_COREPACK=1. Keep that value in the form. Treat the button as a setup shortcut, not as a prebuilt deployment or a substitute for owning the repository. Confirm the repository and project settings before deploying.

Import and deploy

1. Push the configured repository to your Git provider.

2. In Vercel, select Add New > Project, import the repository, and leave Root Directory at the repository root.

3. Vercel should detect Astro. Expand Environment Variables, add ENABLE_EXPERIMENTAL_COREPACK with value 1, and apply it to Production, Preview, and Development. The README deploy button pre-fills this variable.

4. Before selecting Deploy, verify the committed project configuration:

   Setting	Exact value
   Framework Preset	Astro
   Root Directory	repository root (empty)
   Install Command	pnpm install --frozen-lockfile
   Build Command	pnpm build
   Output Directory	dist
   Node.js	24.x
   Required build environment variable	ENABLE_EXPERIMENTAL_COREPACK=1
   Application secrets	none

   vercel.json overrides the Install Command, Build Command, and Output Directory in Project Settings for each deployment. Keep those settings in version control; do not create competing dashboard overrides.

5. Select Deploy, then open the assigned *.vercel.app production URL.

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

Astro emits dist/404.html; Vercel serves that file with a 404 response for unmatched static paths without a rewrite. The committed vercel.json translates StarryBio’s CSP, browser-security headers, and cache rules because Vercel does not read public/_headers directly. Do not add a catch-all rewrite to index.html.

Continuous deployment and updates

Vercel creates a production deployment for the production branch. For an imported repository that has main, Vercel selects main by default; other branches normally receive Preview Deployments. To use another branch, set it in the project’s Production environment branch tracking.

For a routine 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 to the production branch.
4. Review the Vercel build log and test the new production deploy.

To redeploy an existing revision, open the project’s Deployments sidebar item, find the deployment, open the … menu, choose Redeploy, then confirm the cache choice and deployment. A dashboard redeploy cannot include uncommitted local changes.

Custom domain

1. Open the Vercel project, choose Settings in the sidebar, then choose Domains.
2. Select Add Domain, enter the exact hostname such as links.example.com or example.com, and assign it to Production.
3. Follow the DNS record shown for that project. For DNS held outside Vercel, add the exact requested record at that provider; Vercel may request an A record for an apex domain, a project-specific CNAME for a subdomain, or nameserver delegation. Do not reuse a target from another Vercel project.
4. Wait until the domain status shows configured and Vercel provisions HTTPS.
5. Update seo.canonicalUrl and qr.url to the exact https:// canonical URL, commit, and push.

Add both an apex and www host only when you intend to serve or redirect both. Configure the redirect in Settings > Domains so the non-canonical hostname cannot create duplicate content. StarryBio itself does not implement hostname redirects.

Troubleshooting

Vercel reports the wrong framework, package manager, or output directory

Check that Root Directory is the repository root and that it contains vercel.json, package.json, pnpm-lock.yaml, and .node-version. The committed vercel.json must contain the exact install command, pnpm build, and dist; those configuration fields override the project dashboard values. Then check Settings > Environment Variables for ENABLE_EXPERIMENTAL_COREPACK=1 in Production, Preview, and Development. Without it, Vercel can select an older pnpm that cannot honor StarryBio’s pinned pnpm 12 toolchain.

A change deploys as a preview instead of production

Push or merge the change to the configured production branch. Check the branch under the project’s Production environment branch-tracking settings before changing code or domain settings.

A custom domain points to an old deployment or does not verify

Open Settings > Domains, confirm the hostname is assigned to this project’s Production environment, and use the exact DNS value Vercel displays for that domain. Remove only conflicting stale records after confirming their purpose. Then update canonical metadata in the source and push a new production deployment.

Headers or CSP are missing

Vercel uses the headers entries in vercel.json, not public/_headers. Run pnpm headers after changing analytics; validation rejects stale generated Vercel headers.

For current provider details, consult Vercel’s Git deployment guide, build configuration guide, package-manager guide, version-controlled project configuration, deployment management guide, and custom-domain guide. Astro’s general deployment guide confirms the static dist output contract.