Configuration

The quickback.config.ts file configures your Quickback project. It defines which providers to use, which features to enable, and how the compiler generates code.

import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";

export default defineConfig({
  name: "my-app",
  template: "hono",
  auth: {
    // Required for "+" role expansion in access rules (e.g. roles: ["member+"]).
    // Lowest → highest. Omit if you always list roles explicitly.
    roleHierarchy: ["member", "admin", "owner"],
  },
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("cloudflare-d1"),
    auth: defineAuth("better-auth"),
  },
});

Discoverable options block

After your first quickback compile, the file gets a managed block bracketed by sentinel comments:

export default defineConfig({
  name: "my-app",
  template: "hono",
  providers: cloudflare({}),

  // [quickback:options-start]
  // ── Project ──
  //
  // Primary custom domain (auto-inferred from cms/account/api domains if unset).
  // domain: "example.com",
  //
  // ── Embedded UIs (CMS / Account) ──
  //
  // Login/signup/profile/orgs SPA. Set `true` for default, or object to customize.
  // account: {
  //   fileUploads: false,           // show the avatar upload UI on the profile page
  //   auth: { passkey: false, emailOTP: false, ... },
  //   ...
  // },
  //
  // ... every other option Quickback supports
  // [quickback:options-end]
});

This block is regenerated on every compile — the compiler is the source of truth, so newly added options surface automatically when you upgrade Quickback (no CLI bump needed).

To enable an option, copy the line you care about above the [quickback:options-start] sentinel and uncomment it:

export default defineConfig({
  name: "my-app",
  template: "hono",
  providers: cloudflare({}),

  account: {
    fileUploads: true,    // ← lifted out of the managed block
  },

  // [quickback:options-start]
  // ... account is now omitted from this block on next compile
  // [quickback:options-end]
});

Quickback notices that account is set above the marker and drops it from the managed block on the next compile to avoid duplicate definitions. Anything outside the marker block is yours and never touched.

If you ever want to opt out of the auto-managed block, run:

quickback compile --no-sync-config

Required Fields

Optional Fields

Every optional top-level key the config accepts is listed below. You never have to memorize them — after your first compile, the discoverable options block lists each one (minus the ones you've set) right inside your quickback.config.ts. This table is the human reference; follow the links for detailed pages.

Public contract version

Quickback defaults to the existing v1 HTTP contract. New applications can opt into v2 explicitly:

export default defineConfig({
  name: "my-app",
  template: "hono",
  contract: { version: "v2" },
  providers: cloudflare({}),
});

The selection is atomic: feature routes move to /api/v2/*, Better Auth moves to /auth/v2/*, and generated OpenAPI, MCP tool calls, OAuth discovery, llms.txt, schema/embeddings routes, and dedicated-domain /v2/* shortcuts use the same version. When CMS or Account is enabled, Quickback also bakes those paths into the SPA build and injects them at runtime, so CRUD, schema, live-view, and authentication requests use the selected contract. Quickback does not expose a mixed v1/v2 surface from one compiled Worker. Omitting contract remains byte-compatible with v1 projects.

V2 also makes action input-schema fidelity a compile gate. The CLI must successfully harvest z.toJSONSchema(action.input) for every authored action; partial or missing harvests fail with the exact action file keys, bundle or evaluation phase, and underlying local error. Dependencies are resolved from the generated runtime's build.outputDir/node_modules before unrelated ancestor installs, so an isolated quickback/ definition tree can use a sibling src/ runtime without a workspace-root symlink. The compiler enforces the same invariant at its shared input boundary, including POST /compile?complete=false, so validation-only or raw API calls cannot bypass it. V1 retains the historical best-effort static-schema fallback.

The version selection also moves the event and read surfaces:

See API Contract for the full v1 → v2 matrix and migration sequencing.

Delegated principals (contract v2)

auth.principals defines non-account authority such as an event pass or a short-lived event session. It is available only with all three of:

• contract: { version: "v2" }
• the Cloudflare runtime
• Neon with connectionMode: "hyperdrive"

Each principal type owns an exact Authorization scheme. Bearer is reserved for Quickback account authentication, including case variants, and two principal types cannot share a scheme.

export default defineConfig({
  name: "attend-v2",
  template: "hono",
  contract: { version: "v2" },
  auth: {
    principals: {
      event_pass: {
        scheme: "EventPass",
        authenticate: {
          module: "./event-pass-proof",
          export: "authenticateEventPass",
        },
        lookup: {
          table: {
            module: "../features/event-access/event-access",
            export: "eventAccess",
            sqlName: "event_access",
          },
          digest: { field: "digest", column: "digest" },
          actorId: { field: "personId", column: "person_id" },
          claims: {
            eventId: { field: "eventId", column: "event_id" },
            personId: { field: "personId", column: "person_id" },
          },
          status: { field: "status", column: "status", allow: ["active"] },
        },
      },
      event_delegate: {
        scheme: "EventSession",
        authenticate: {
          module: "./event-session-proof",
          export: "authenticateEventSession",
        },
        lookup: {
          table: {
            module: "../features/event-sessions/event-sessions",
            export: "eventSessions",
            sqlName: "event_sessions",
          },
          digest: { field: "digest", column: "digest" },
          actorId: { field: "personId", column: "person_id" },
          sessionId: { field: "id", column: "id" },
          familyId: { field: "familyId", column: "family_id" },
          claims: {
            eventId: { field: "eventId", column: "event_id" },
            personId: { field: "personId", column: "person_id" },
          },
          status: { field: "status", column: "status", allow: ["active"] },
        },
      },
    },
  },
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("neon", {
      connectionMode: "hyperdrive",
      hyperdrive: { id: "<32-character-hyperdrive-id>" },
    }),
    auth: defineAuth("better-auth"),
  },
});

The authenticate.module path is relative to generated src/lib/principal-auth.ts. Put project proof hooks under quickback/lib; the compiler stages them into src/lib even if no action imports them. A hook has one job: prove the presented credential and return its stable digest.

// quickback/lib/event-session-proof.ts
export async function authenticateEventSession({ credential, env, request }: {
  credential: string;
  env: Env;
  request: Request;
}): Promise<{ digest: string } | null> {
  const valid = await verifySignedEventSession(credential, env, request);
  return valid ? { digest: await sha256(credential) } : null;
}

The hook receives no db, and it must not implement row authorization or business behavior. Quickback performs exactly one narrow, unique digest lookup under a lookup-only RLS principal. A digest must be 16–512 non-whitespace characters; resolved identity strings must be 1–512 characters and serialized claims are limited to 4096 characters. A lookup must resolve exactly one active row or authentication fails.

On success, actions receive ctx.principal:

{
  type: "event_delegate",
  actor: { type: "event_delegate", id: "person_123" },
  session: { id: "session_123", familyId: "family_123" },
  claims: { eventId: "event_123", personId: "person_123" },
}

Quickback never synthesizes userId, activeOrgId, activeTeamId, or membership roles from a delegated credential. Use principals in an access arm to admit it. Values inside one arm are ANDed; sibling or arms are ORed:

access: {
  or: [
    { roles: ["AUTHENTICATED"] },
    { principals: ["event_delegate"], record: {
      eventId: { equals: "$ctx.principal.claims.eventId" },
    } },
  ],
}

An Authorization header cannot be combined with x-api-key or a Better Auth session cookie. Quickback recognizes only Better Auth's exact session cookie names for this conflict check, so analytics and preference cookies remain harmless.

Custom Dependencies

Add third-party npm packages to the generated package.json using build.dependencies. This is useful when your action handlers import external libraries.

export default defineConfig({
  name: "my-app",
  template: "hono",
  build: {
    dependencies: {
      "fast-xml-parser": "^4.5.0",
      "lodash-es": "^4.17.21",
    },
  },
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("cloudflare-d1"),
    auth: defineAuth("better-auth"),
  },
});

These are merged into the generated package.json alongside Quickback's own dependencies. Run npm install after compiling to install them.

Headless Migration Rename Hints

When drizzle-kit generate detects a potential rename, it normally prompts for confirmation. Cloud/CI compiles are non-interactive, so you must provide explicit rename hints.

Add hints in compiler.migrations.renames:

export default defineConfig({
  // ...
  compiler: {
    migrations: {
      renames: {
        // Keys are NEW names, values are OLD names
        tables: {
          events_v2: "events",
        },
        columns: {
          events: {
            summary_text: "summary",
          },
        },
      },
    },
  },
});

Rules:

• tables: new_table_name -> old_table_name
• columns.<table>: new_column_name -> old_column_name
• Keys must match the names in your current schema (the new names)
• Validation fails fast for malformed rename config, unsupported keys, or conflicting legacy/new rename paths.

Neon Foreign Key Migrations

Use compiler.migrations.foreignKeys when a Neon relationship cannot be expressed in one generated Drizzle schema file—for example, a feature table that references a Better Auth table, or a composite integrity relationship between independently authored feature modules.

export default defineConfig({
  // ...
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("neon", { connectionMode: "hyperdrive" }),
    auth: defineAuth("better-auth"),
  },
  compiler: {
    migrations: {
      foreignKeys: [
        {
          name: "person_account_links_user_fk",
          source: {
            schema: "app",
            table: "person_account_links",
            columns: ["user_id"],
          },
          target: {
            schema: "auth",
            table: "users",
            columns: ["id"],
          },
          onDelete: "restrict",
          onUpdate: "restrict",
        },
        {
          name: "event_access_grants_consumed_family_fk",
          source: {
            schema: "app",
            table: "event_access_grants",
            columns: [
              "consumed_by_family_id",
              "id",
              "organization_id",
              "event_id",
              "event_person_id",
            ],
          },
          target: {
            schema: "app",
            table: "event_session_families",
            columns: [
              "id",
              "source_grant_id",
              "organization_id",
              "event_id",
              "event_person_id",
            ],
          },
          onDelete: "restrict",
          onUpdate: "restrict",
        },
      ],
    },
  },
});

All identifiers must be lowercase Postgres identifiers of at most 63 characters. Source and target tuples must be nonempty and have equal arity; column order is significant. Supported actions are "no action", "restrict", "cascade", "set null", and "set default".

Constraint names and source tuples must be unique in the config. On replay, Quickback verifies that an existing same-named constraint has the exact target, ordered columns, and referential actions. It fails instead of silently accepting an ambiguous definition. Existing rows are validated during migration, so clean up orphans before deploying.

This API is for database integrity, not business behavior. Keep authorization, state transitions, event-pass consumption, and other business rules in the API action layer.

Disable Audit Field Injection

Quickback manages four audit columns (createdAt, modifiedAt, createdBy, modifiedBy) on every feature table, plus two soft-delete columns (deletedAt, deletedBy) on tables whose resource uses soft delete (the default delete mode). The audit columns drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.

You declare them in the table's columns object with ...q.audit() and ...q.softDelete(). The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run quickback migrate visible-columns to adopt the declarations on an existing project. Set compiler.features.visibleAuditColumns: false to downgrade those checks to warnings and keep the pre-v0.57.0 silent-injection behavior.

To opt out of the managed columns entirely, project-wide:

export default defineConfig({
  name: "my-app",
  compiler: {
    features: {
      auditFields: false,  // skip audit-field injection globally
    },
  },
  providers: { /* ... */ },
});

When disabled, you're responsible for supplying these columns yourself if you want soft delete, audit trails, or modifiedAt-based optimistic concurrency. See the Schema → Audit Fields section for the full list and what each field drives.

Security Contract Reports and Signing

After generation, Quickback verifies machine-checkable security contracts for Hono routes and RLS SQL.

It also emits a report artifact and signature artifact by default:

• reports/security-contracts.report.json
• reports/security-contracts.report.sig.json

You can configure output paths and signing behavior:

export default defineConfig({
  // ...
  compiler: {
    securityContracts: {
      failMode: "error", // or "warn"
      report: {
        path: "reports/security-contracts.report.json",
        signature: {
          enabled: true,
          required: true,
          keyEnv: "QUICKBACK_SECURITY_REPORT_SIGNING_KEY",
          keyId: "prod-k1",
          path: "reports/security-contracts.report.sig.json",
        },
      },
    },
  },
});

If signature.required: true and no key is available, compilation fails with a clear error message (or warning in failMode: "warn").

Hostname architecture (v0.33+)

A modern Quickback project runs on one Cloudflare Worker that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as quickback.{baseDomain} from your other configured subdomains, or overridable via config.domain). For larger deployments, you can opt-in to dedicated hostnames for specific surfaces — they're additive aliases, never replacements.

The unified backend contract

When any subdomain is configured (account.domain, cms.domain, auth.domain, api.domain, apps.<n>.domain), the compiler always emits a unified backend host where every compiler-emitted backend route is reachable:

• /api/v1/* and /auth/v1/* for the default contract, or /api/v2/* and /auth/v2/* when contract.version is "v2"
• /storage/* — R2 file storage
• /health, /openapi.json — monitoring/discovery
• /account/*, /cms/* — bundled SPAs (when enabled)
• /broadcast/v1/* (realtime; /broadcast/v2/* under contract.version: 'v2'), /mcp (MCP), etc.

The unified hostname is quickback.{baseDomain} by default (where baseDomain is extracted from your first configured subdomain). Override with config.domain if you prefer a different name.

This contract is forward-pointing: it gives a stable URL pattern for future management tooling — https://quickback.{baseDomain}/... will always reach a Quickback backend regardless of how the operator splits their surfaces.

Dedicated hostnames (optional, additive)

For branding or operational separation, you can opt specific surfaces onto their own hostnames:

{
  // Bundled SPAs on their own hosts (already-shipped pattern):
  cms:     { domain: 'cms.example.com' },
  account: { domain: 'account.example.com' },

  // v0.33+ — backend surfaces on their own hosts:
  auth:    { domain: 'auth.example.com' },
  api:     { domain: 'api.example.com'  },

  // User SPAs (existing pattern):
  apps: {
    www:   { domain: 'app.example.com' },
  },
}

On a dedicated hostname, the hostname IS the namespace — the path drops the prefix that matches the hostname:

Dual-reach is preserved on the unified host:

Each dedicated hostname also:

• Gets a { pattern, custom_domain: true } route in wrangler.toml automatically
• Joins trustedOrigins for CORS
• Joins the cross-subdomain cookie inference (auto-enables crossSubDomainCookies when ≥2 same-parent subdomains are configured, so auth.example.com and app.example.com can share session cookies)
• Joins CSP connect-src so SPAs can fetch from it

Why two URL shapes (Shape 1 vs Shape 2)

If you only want Better Auth to advertise itself on a different URL (e.g. so verification emails link to auth.example.com instead of the unified host), set the BETTER_AUTH_URL env var on the Worker — no code change required. BA generates outgoing URLs against that value. This is sufficient when the goal is branding email/OAuth callback URLs without changing where requests actually land.

auth.domain (Shape 1, above) is the heavier option: it binds an actual hostname to the Worker, configures CORS/cookies/CSP for it, and adds the path-shortcut rewriter. Use it when you want the dedicated hostname as a real ingress, not just a label.

CMS Configuration

Embed the Admin UI in your compiled Worker. It reads your schema registry and renders a complete admin interface — zero UI code per table.

// Simple — embed CMS at root
cms: true,

// With custom domain
cms: { domain: "cms.example.com" },

// With access control (only admins can access CMS)
cms: { domain: "cms.example.com", access: "admin" },

// Cross-tenant DB-admin tier — sysadmins see every tenant's data
cms: { domain: "cms.example.com", sysadmin: true },

Sysadmin tier (cms.sysadmin: true)

Quickback's default model assumes every CMS user belongs to at least one organization (member row in the auth DB). For platforms that need a Supabase-style cross-tenant DB-admin tool — debugging a tenant's data, running cross-tenant queries, supporting a customer — that's a poor fit: a sysadmin without member rows would dead-end, and auto-filling their active org from "first membership" silently scopes them to a tenant they have no relationship with.

cms: { sysadmin: true } introduces a separate role tier:

• Role: user.role === "sysadmin" (set on the Better Auth user table). Distinct from "appmanager" — appmanagers keep platform control-plane access (CMS shell, Better Auth admin surfaces, support tooling), while sysadmins get true cross-tenant data access. ADMIN is now a rejected legacy pseudo-role; use userRole: ["appmanager"] for control-plane gates and roles: ["SYSADMIN"] for cross-tenant access.
• Firewall: every buildFirewallConditions() emits an if (ctx.userRole === "sysadmin") return undefined (or just the soft-delete predicate when present) at the top, so sysadmins see every tenant's rows. See Firewall escape hatch.
• Org listing: a GET /auth/v1/admin/list-organizations endpoint selects directly from the auth-schema organization table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of /auth/v1/admin/list-users) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to user.role === "sysadmin" only. For the membership-bound caller's-orgs listing, use BA's own /auth/v1/organization/list.
• CMS SPA: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits ?organizationId= and reaches the firewall escape), and pins selected tenants via ?organizationId= on every API call. Org admins keep the existing membership-based switcher.
• CMS HTML gate: admits userRole === "sysadmin" alongside "appmanager". Org admins are not locked out when you set cms.access: "user"; cms.access: "admin" is specifically the platform control-plane gate.

Off by default. Projects that don't enable it get zero behavior change; setting cms.sysadmin: true and granting a user user.role = "sysadmin" is the only way to unlock the cross-tenant view.

Account UI Configuration

Embed the Account UI in your compiled Worker. Provides login, signup, profile management, organization management, and admin — all built from your config at compile time.

For post-signup logic — auto-provisioning a workspace, gating signup, setting an active organization — drop a file in quickback/hooks/. See Auth Hooks.

// Simple — embed Account UI with defaults
account: true,

// Full configuration
account: {
  domain: "auth.example.com",
  adminDomain: "admin.example.com",
  name: "My App",
  companyName: "My Company",
  auth: {
    password: true,
    emailOTP: false,
    passkey: true,
    organizations: true,
    admin: true,
  },
},

Auth Feature Flags

Control which authentication features are exposed. Disabled features are excluded from the Account UI bundle at compile time (routes removed before the Vite build, keeping bundle sizes minimal) and enforced on the server side via the Better Auth config — so "signup off" actually closes POST /auth/v1/sign-up/email, not just the SPA's signup screen.

account.auth.* is a shorthand for providers.auth.config — the compiler maps each flag onto the Better Auth server config before any code is generated. You can write either side directly; setting both incompatibly (e.g. account.auth.signup: false and emailAndPassword.disableSignUp: false) fails the compile with a precise error rather than picking a silent winner.

Trusted Origins

List of origins allowed to make cross-origin requests to your API. Required when your CMS, Account UI, or frontend app run on different domains.

trustedOrigins: [
  "https://auth.example.com",
  "https://admin.example.com",
  "https://cms.example.com",
  "https://app.example.com",
],

Local Development

Configure local development URLs. These are automatically added to the trusted origins list for CORS and Better Auth, so authentication works out of the box during local development.

dev: {
  port: 8787,                                // wrangler dev port (default: 8787)
  api: "http://localhost:8787",              // API backend URL
  cms: "http://localhost:8787/cms",          // CMS URL (path on same worker)
  account: "http://localhost:8787/account",  // Account URL (path on same worker)
},

If you run a SPA standalone on its own Vite dev server, set its URL here so CORS allows it:

dev: {
  port: 8787,
  api: "http://localhost:8787",
  account: "http://localhost:5173",  // standalone Account dev server
},

Email Configuration

Configure email delivery for authentication emails (verification, password reset, invitations).

Cloudflare Email Sending is now in public beta and is Quickback's default transport for Cloudflare deploys. The Workers send_email binding is zero-config — no API keys, no third-party accounts. AWS SES remains supported as an explicit opt-in (email.provider: 'aws-ses') for non-Cloudflare runtimes or existing SES setups.

// Cloudflare Email Service (default) — uses send_email binding, no API keys needed
email: {
  from: "noreply@example.com",
  fromName: "My App",
},

// AWS SES — requires AWS credentials set as Wrangler secrets
email: {
  provider: "aws-ses",
  region: "us-east-2",
  from: "noreply@example.com",
  fromName: "My App",
},

Auto-wiring

For the Cloudflare provider (the default), the compiler automatically:

• Emits [[send_email]] EMAIL into wrangler.toml
• Generates src/lib/cloudflare-email.ts
• Wires sendResetPassword, sendVerificationEmail, sendInvitationEmail, etc. into Better Auth
• Types the binding with Cloudflare's native SendEmail / EmailSendResult contract ({ email, name }, replyTo, and contentId on Workers). The REST helper remains a separate { address, name } / reply_to / content_id contract.
• Anchors each authentication delivery to executionCtx.waitUntil(...). The background promise records a structured generic failure and stays rejected; outside a Worker request, the callback returns the observed promise for the caller to await. Every Cloudflare Email callback is wired through that shared scheduler exactly once, so no auth action can bypass failure observation or double-schedule the send. Provider error bodies are never written to generated logs.

…whenever any auth surface needs to send mail — emailAndPassword.enabled, the emailOtp / magicLink / organization plugins — or you set the top-level email: {…} config. You don't need to add bindings.sendEmail by hand for the standard cases.

Cloudflare Email Routing setup is required. The binding alone does not deliver mail. Enable Email Routing on the sending zone and add at least one verified destination address (Cloudflare docs). Otherwise sends fail at runtime even with the binding present and the /auth/v1/ses/status check passing locally.

Multi-Domain Example

A complete config with CMS, Account UI, and Admin on separate subdomains:

export default {
  name: "my-app",
  template: "hono",
  cms: { domain: "cms.example.com", access: "admin" },
  account: {
    domain: "auth.example.com",
    adminDomain: "admin.example.com",
    name: "My App",
    companyName: "Example Inc.",
    auth: {
      password: true,
      emailOTP: false,
      passkey: true,
      organizations: false,
      admin: true,
    },
  },
  email: {
    from: "noreply@example.com",
    fromName: "My App",
  },
  trustedOrigins: [
    "https://auth.example.com",
    "https://admin.example.com",
    "https://cms.example.com",
    "https://example.com",
  ],
  providers: {
    runtime: { name: "cloudflare", config: {
      routes: [{ pattern: "api.example.com", custom_domain: true }],
    }},
    database: { name: "cloudflare-d1", config: { binding: "DB" } },
    auth: { name: "better-auth", config: { plugins: ["admin"] } },
  },
};

This produces a single Cloudflare Worker serving five domains. See Multi-Domain Architecture for details on hostname routing, cross-subdomain cookies, and the unified fallback domain.

See the sub-pages for detailed reference on each section:

• Providers — Runtime, database, and auth options
• Variables — Environment variables and flags
• Output — Generated file structure
• Pinned Organization Mode — Fixed-org deployments without org switching UI
• Multi-Domain Architecture — Custom domains, hostname routing, and cross-subdomain auth