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",
  features: { organizations: true },
  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

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.

Disable Audit Field Injection

By default, Quickback auto-injects four audit fields (createdAt, createdBy, modifiedAt, modifiedBy) into every feature table, plus two soft-delete fields (deletedAt, deletedBy) into tables that use soft delete (the default delete mode). The audit fields drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.

To opt out 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").

CMS Configuration

Embed the Quickback CMS in your compiled Worker. The CMS 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 "admin" — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant.
• 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 new GET /admin/v1/sysadmin/organizations endpoint selects directly from the auth-schema organization table — every row, every tenant. The existing /admin/v1/organizations (membership-bound, used by org admins) is unchanged.
• 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 "admin". Org admins are not locked out — both roles can enter the CMS in cms.access: "admin" mode.

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

…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
• Single-Tenant Mode — Admin-only and public-facing apps without organizations
• Multi-Domain Architecture — Custom domains, hostname routing, and cross-subdomain auth