Operations and Updates

Operating StarryBio is largely a build-and-deploy workflow. There is no live content database to migrate and no server process to restart; each release replaces the static artifact at the selected host.

Routine content change

For a link, profile, theme, status, or analytics change:

1. Edit config/starrybio.config.ts or an asset under public/.

2. Use pnpm dev to review the change locally.

3. Run the production checks.

   pnpm validate
   pnpm build
   pnpm preview

4. Deploy with the selected provider:

   • GitHub Pages: commit and push to main; the Pages workflow builds and deploys automatically.

   • Vercel or Netlify: commit and push to the configured production branch; the connected Git project builds and deploys automatically.

   • Cloudflare Workers: run the bundled deploy command.

     pnpm deploy

5. Verify the canonical production URL, an unknown route, and any generated download or third-party analytics integration you enabled.

Generated files are rebuilt on each build. You do not upload them manually, and disabling an enabled generator removes its configured and default output before the new static build.

Update StarryBio

Run the updater from your StarryBio directory:

pnpm starrybio:update

It checks for a newer release, prepares the update, and asks before installing. Your configuration and custom files are preserved when they can be merged safely. If a customization conflicts with the release, the current installation is left unchanged and the updater reports the affected paths.

Useful options:

pnpm starrybio:update --dry-run
pnpm starrybio:update --check
pnpm starrybio:update --yes

After a successful update, preview the site and deploy it again:

pnpm release:check
pnpm preview

v2 to v3 configuration migration

StarryBio v3 rejects legacy and unknown configuration fields. Make these changes before building a migrated configuration:

Earlier configuration	v3 configuration
Top-level links	Required sections: [{ title, links }]
Link text	Link label
Theme bright	classic-blue
status.showLocalTime	status.showVisitorTime
status.showOwnerLocalTime	status.showOwnerTime
Status schedule in owner/UTC time	Schedule evaluated in each visitor’s local time
CDN icon download on every build	Build-time local Simple Icon generation from the pinned package

If showOwnerTime is true, set a valid IANA ownerTimeZone. This only controls the optional owner clock—do not use it to preserve previous schedule semantics. Revisit every status interval with the visitor-local rule in Availability and Announcements.

Run pnpm validate after migration. Its field path is the fastest way to locate an unsupported key or missing required value.

Back up what matters

The source repository is the authoritative backup for a static site:

• Commit config/starrybio.config.ts, authored assets under public/, wrangler.jsonc, and source modifications.
• Keep the lockfile (pnpm-lock.yaml) committed so builds use the reviewed dependency graph.
• Do not rely on generated icon, QR, OG image, or vCard files as the only copy; they are reproducible and ignored by Git.
• Record the intended Cloudflare account, Worker name, canonical hostname, and analytics provider outside the site if more than one person operates it.

There is no StarryBio database export, account backup, or storage-bucket backup because the stock application does not use those services.

Roll back a bad deployment

Cloudflare Worker version rollback is available independently of StarryBio. First identify the prior version in the Cloudflare dashboard or with the bundled CLI:

pnpm exec wrangler versions list

To choose a version interactively, or to revert to the version immediately before the latest deployment:

pnpm exec wrangler rollback

To select a known version explicitly:

pnpm exec wrangler rollback <VERSION_ID>

A rollback immediately creates a new active Worker deployment for its attached routes and domains; it does not change your local checkout. Cloudflare retains a limited recent version history, so do not treat rollback as a long-term archive. The stock StarryBio Worker has no data bindings, which avoids the binding/data compatibility concerns of stateful Workers.

After rollback, verify the canonical URL and write down why the change was reverted. Fix or revert the corresponding source change before the next pnpm deploy, otherwise a later deploy simply reintroduces it.

Recovery when local files are lost

1. Clone or restore the last known-good Git revision.
2. Install its locked dependencies with pnpm install.
3. Confirm config/starrybio.config.ts, public/ assets, and wrangler.jsonc contain the intended identity, Worker name, and domain behavior.
4. Run pnpm release:check and pnpm preview.
5. Deploy the known-good commit or use the Cloudflare version rollback above for a faster traffic recovery.

If you cannot reconstruct a customized local asset because it was never committed, it cannot be recovered from StarryBio itself. The deployed Cloudflare asset can be viewed publicly if its URL is known, but that is not a reliable source-control substitute.

See Troubleshooting for a failed update and Security and Privacy before sharing configuration or deployment diagnostics.