Deploying

Building in Quickback Start instead of locally? You can also deploy straight from the browser — no CLI needed.

A freshly compiled project's wrangler.toml contains placeholder resource ids — the compiler can't know your D1 database ids or KV namespace id until those resources exist in your Cloudflare account. Historically that meant a manual dance: wrangler d1 create, copy the id, paste it into quickback.config.ts, repeat for every database, recompile, deploy.

quickback deploy does the whole dance for you:

cd my-app && quickback deploy

What it does

1. Preflight — verifies wrangler is runnable (via npx) and authenticated with Cloudflare (wrangler whoami). Log in with npx wrangler login or set CLOUDFLARE_API_TOKEN.

2. Compiles first if needed — if the project has never compiled (no wrangler.toml), it runs the same flow as quickback build before planning anything.

3. Plans from wrangler.toml — reads the generated wrangler.toml and finds every resource whose id is still a placeholder:

   • D1 databases — auth, features, files, webhooks, and audit databases (whichever your project's features pull in; split-database projects get one entry each)
   • KV namespace — the KV binding used for rate limiting and session overflow
   • R2 buckets — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)

4. Creates what's missing — wrangler d1 create <name>, wrangler kv namespace create <BINDING>, wrangler r2 bucket create <name>. Resources are named from your project name exactly the way the compiler names them (my-app-auth, my-app-features, my-app-files, my-app-KV, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.

5. Writes ids back into quickback.config.ts — a surgical, formatting-preserving edit of your providers.database.config (and providers.storage.config for the KV id when you declare a cloudflare-kv storage provider). Comments, indentation, and every other key are left untouched. Works with both authoring styles:

   // defineDatabase(...) wrapper
   database: defineDatabase("cloudflare-d1", {
     splitDatabases: true,
     authDatabaseId: "…",       // ← inserted/updated here
     featuresDatabaseId: "…",
   }),
   
   // plain object form
   database: {
     name: "cloudflare-d1",
     config: {
       authDatabaseId: "…",     // ← or here
     },
   },

6. Recompiles — so wrangler.toml regenerates with the real ids.

7. Applies D1 migrations remotely — wrangler d1 migrations apply <db> --remote for each database that has pending migration files (each database's migrations_dir comes straight from wrangler.toml).

8. Deploys — wrangler deploy, streaming wrangler's output.

Idempotent by design

Run it again any time. When every id is real, there's nothing to create — the command goes straight to compile → migrations → deploy. It's a perfectly good everyday "ship it" command, not just a first-deploy tool.

Flags

# See the plan without touching your account
quickback deploy --dry-run

# Provision + write ids only; deploy later
quickback deploy --skip-deploy

Named deployment targets

quickback deploy --env dev
quickback deploy --env prod --dry-run

The argument is the logical config key. If dev declares worker.env: "preview-blue" and name: "existing-dev-worker", Quickback selects [env.preview-blue], migrates only that target's D1 bindings with --env preview-blue, and uploads that Worker. Top-level bindings are not inherited. Both environment placements are supported; declaring both is an error. Missing or unknown targets stop before resource creation, migrations, or upload.

Named targets must already have their D1, KV and Hyperdrive IDs configured in their own worker.bindings. If an ID is a placeholder, deployment stops before provisioning; create that target's resources manually, enter its IDs and run quickback build. The CLI does not splice named IDs into global provider config. R2 buckets declared by the selected target are still ensured by name. --force does not bypass these checks. --skip-deploy skips migrations and upload, and --dry-run reports without creating resources.

Postgres migrations remain a separate operator-owned step, including for named Neon targets. quickback deploy --env dev selects the Worker but does not verify that the Hyperdrive origin matches the intended Neon branch, inspect remote query caching, or apply Postgres migrations. Configure Hyperdrive with query caching disabled and migrate the intended branch before deployment.

Conflicting ids

If quickback.config.ts already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, quickback deploy prints both and stops:

✖ Config ids differ from what Cloudflare reports:
    providers.database.config.authDatabaseId
      in quickback.config.ts: 13b688c8-…
      from Cloudflare:        f6b8f9a0-…

Re-run with --force to take Cloudflare's value, or fix the config by hand.

Notes

• Security-audit database — projects using unsafe, PUBLIC, or hard-delete actions get an AUDIT_DB D1. Compile emits a placeholder id; quickback deploy creates the database and writes auditDatabaseId back, same as AUTH_DB / features DB. Direct wrangler deploy of the placeholder fails Cloudflare 10021 — use quickback deploy.
• Neon projects — quickback deploy does not apply Postgres migrations. Run npm run db:migrate (needs DATABASE_MIGRATION_URL) before traffic hits the worker, or use the generated project's npm run deploy script which chains both.
• Hyperdrive — a Hyperdrive binding can't be auto-created (it needs your database connection string). Create it with wrangler hyperdrive create <name> --connection-string=… --caching-disabled and set providers.database.config.hyperdrive.id.
• Two logins — the compile step uses your Quickback account (quickback login); resource creation and deploy use your wrangler credentials.