Upgrading

Use this guide when your product already contains custom code or data and you want to pull a newer template version. For a new installation, follow Quick Start instead.

Keep Your Product in Your Own Repository

Create a private repository for your product. If you cloned the template directly and origin still points at it, rename that remote to upstream, then add your own repository:

git remote -v
git remote rename origin upstream
git remote add origin YOUR_PRIVATE_REPOSITORY_URL
git push -u origin HEAD

Do not run the rename if your origin already points to your product or an upstream remote already exists. Inspect git remote -v and adapt the setup. Keep your repository private according to your license.

Bring In an Update on a Separate Branch

Commit your current product work and take backups first. From a clean working tree:

git switch -c upgrade/template-update
git fetch upstream
git merge upstream/main
pnpm install

Resolve conflicts while preserving your product behavior. Do not merge unreviewed database changes straight into production. The following comparison explains the current monorepo changes for older single-app/Hyperdrive projects; it is not an automatic production migration script.

Layout Changes

• Node app: apps/web, for Vercel/Docker, with pooled Postgres and S3-compatible storage.
• Workers app: apps/web-cloudflare, with D1 DB, native R2 R2_BUCKET, and Cloudflare Email Sending. The former Hyperdrive architecture is not the current template path.
• Shared factories and pure logic: packages/*. Apps keep full page copies, not a shared page package.
• MDX belongs to each app’s content/, not a root shared content directory.
• Messages belong to packages/i18n/src/translations/{en,zh}/; load default.json, then deep-merge mvp.json. Derivatives edit only mvp.json.
• Product gates live in packages/config/src/index.ts; pricing display and purchasable items remain in app src/config/saas/.

Removed Surfaces and New Configuration

/app/admin/settings, settings APIs, encrypted settings storage, MUSE_SETTINGS_SECRET, and connection-strategy switches are not current features. Billing, captcha, mail, and Node S3 credentials are server-side environment variables. Remove links to the old admin-settings page.

Legacy mail variables map to MAIL_FROM, MAIL_FROM_NEWSLETTER, and CONTACT_FORM_TO, without fallback. The latest version has no legacy settings-export CLI. Securely export/record credentials on the old version before upgrading and inject them on the new host; never put secrets in source control or logs.

Safe Upgrade Order

1. Back up code, database, storage, and credentials; rehearse on an isolated branch/environment.
2. Move actual product changes into routes, modules, wrappers, and packages instead of overwriting whole directories.
3. Move derivative copy into both locales’ mvp.json, preserving upstream default.json.
4. Create the selected app’s .env.local; Workers also needs .dev.vars and resource bindings.
5. Compare old/new schema and migration history. Design incremental migrations for an existing database; the new baseline is for fresh databases.
6. Switching Postgres to D1 needs a separate user/business data migration, addressing SQLite types, constraints, and transactions. A binding does not migrate data.
7. Run checks and verify auth, permissions, billing, uploads, and cross-route navigation in a real app.

pnpm type-check
pnpm check:error
pnpm test:unit
pnpm apps:parity
pnpm build:cf

Use pnpm cf:preview for real Worker bindings. See Testing and Release Checklist.

Current Commands

Do not simply delete an unused application directory; update workspace scripts and tests as well.