Skip to content
BUILD.
← All guides

Upgrade guide · 7 min read

Upgrade to Build 1.7

Keep your projects and configuration, then add approved launches, domains, release history, GitHub imports, enquiry alerts and handover.

Applies to Build 1.1.0 · Updated September 15, 2026

Download this guide (.md)

1. Stop editing and keep a backup

Keep your existing installation and original ZIP. Finish active builds before making a backup. For local installations, stop the server and preserve .wrangler state, .build-local data, private environment files, and custom configuration.

For hosted Agency, back up D1, retain the old Worker version, and record your rollback procedure. Keep backups private and verify you can restore them.

2. Extract the new download separately

Open Your download and get Build 1.7.0. Verify the listed SHA-256, extract it separately, and read docs/UPGRADE-1.7.md before merging into a staged copy. Preserve custom source, data, resource IDs and encryption/signing keys.

The new package reports 1.7.0. The original Build 1.0.0 ZIP inherited an upstream 1.5.0 package version; use its download label and release notes to distinguish it.

Run in your Build folder
node -p "require('./package.json').version"

3a. Update a local Personal installation

Run these from the staged installation after merging the new source and locked dependencies. The installer applies pending local migrations. Confirm an existing project still opens and exports. Personal remains a single-user workflow.

Run in your Build folder
node scripts/install.mjs --profile personal --yes --no-start --json
bun run doctor -- --json
bun run dev:local

3b. Update a hosted Agency installation

Keep your existing Clerk application, Cloudflare resource configuration and private agency settings. Review the plan, then follow the apply procedure in docs/RELEASE.md. An existing operator does not need first-install --bootstrap.

Apply every pending migration before the matching server and frontend. Build 1.7 adds migration 0018 for client launches. Earlier installs also need all prior pending migrations. Keep the existing persistent CF_OAUTH_ENCRYPTION_KEY so saved credentials remain readable. The local installer does not migrate your hosted database.

Run in your Build folder
PUPPETEER_SKIP_DOWNLOAD=true bun install --frozen-lockfile
bun run deploy -- --plan --config wrangler.production.jsonc --env-file .build-local/install/agency.env

4. Check an existing project and a disposable launch

  1. Confirm an existing project opens, previews, exports and stays private. Check its saved provider selection.
  2. In a disposable project, create a fresh client review, approve it as a guest and publish the approved version through Ready → Client launch with your own connected Cloudflare account.
  3. Save a test enquiry, publish another approved version, then restore the earlier code and verify the enquiry is retained. Check the domain setup, reviewed GitHub import, optional alert destination and downloaded handover.
  4. Share a disposable hosted full-stack project as its creator.
  5. Finish editing and have the second member take control.
  6. Make a small build or edit, check the preview, and export source.
  7. Confirm the previous editor cannot write while the teammate has control.
  8. As the creator, make it private after operations finish. Verify the teammate loses access.
Shared previews omit personal Environment bindings. Use a harmless dummy value to verify this behavior. The upgrade does not establish the cause of an existing Clerk sign-in loop.

If a check fails

Preserve the failing state and the old installation. Record the exact step, then follow the rollback procedure from your backup. Do not drop review or revision tables as an improvised rollback.

For hosted installs, review the Worker and database backup together, including writes since the backup. Current deployments and customer data remain your responsibility.

Keep going