With Quickback

When using Account UI with a Quickback-compiled backend, the recommended approach is to let the compiler build and embed the SPA directly into your Worker.

Compiler-Embedded (Recommended)

Add account to your quickback.config.ts:

export default {
  name: "my-app",
  template: "hono",
  account: {
    domain: "auth.example.com",
    name: "My App",
    companyName: "My Company",
    auth: {
      password: true,
      passkey: true,
      organizations: true,
      admin: true,
    },
  },
  // ...providers
};

Then compile and deploy:

quickback compile
npx wrangler deploy

What Happens During Compilation

1. The compiler reads your account config and generates a .env file with the correct Vite environment variables (VITE_QUICKBACK_URL, VITE_QUICKBACK_API_URL, VITE_ENABLE_PASSWORD, branding, etc.)
2. The Account SPA source is copied to a temp directory, with disabled feature routes excluded
3. Pre-installed dependencies are symlinked (no npm install during build)
4. Vite builds the SPA with your settings baked in
5. Built assets (content-hashed filenames) are placed in the output directory

When CMS is also enabled, Account assets go to src/apps/account/ and are served at /account/. When Account is the only SPA, assets go to src/apps/ and are served at root.

Custom Domains

With a custom domain, the Account SPA is served at root (/) on that domain:

account: { domain: "auth.example.com" }

Add an admin domain to serve the admin panel on its own subdomain:

account: {
  domain: "auth.example.com",
  adminDomain: "admin.example.com",
}

See Multi-Domain Architecture for details on hostname routing and cross-subdomain cookies.

Auth Feature Flags

Feature flags control which pages are included in the build:

auth: {
  password: true,       // Email/password login + inline password change
  emailOTP: false,      // Email OTP login flow
  passkey: true,        // WebAuthn passkey setup + management
  organizations: true,  // Dashboard, org management, invitations
  admin: true,          // Admin panel (user management)
}

Disabled features are excluded at compile time — their route files are removed before the Vite build. See Configuration for all options.

Manual Deployment

If you need Account UI as a separate Worker (not embedded in the API Worker), you can deploy it standalone.

1. Clone the Template

npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
cd my-account-app
npm install

2. Configure for Quickback

Set the auth route mode to quickback to match Quickback's API paths:

VITE_AUTH_ROUTE=quickback
# One variable points at the Quickback origin — API, Account, and CMS are all derived from it.
VITE_QUICKBACK_URL=https://secure.example.com
VITE_ACCOUNT_APP_URL=https://account.example.com
VITE_QUICKBACK_APP_URL=https://app.example.com

In Quickback mode, Account UI routes requests to three API paths:

3. Configure Features

Match your quickback.config.ts plugins:

VITE_APP_NAME=My App
VITE_APP_TAGLINE=Build faster, ship sooner
ENABLE_SIGNUP=true
ENABLE_ORGANIZATIONS=true
ENABLE_PASSKEY=true
ENABLE_ADMIN=true

4. Build and Deploy

npm run build
npx wrangler deploy

Library Mode

Install as a dependency instead of cloning:

npm install quickback-better-auth-account-ui

import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
import 'quickback-better-auth-account-ui/styles.css';

setAppConfig({
  authRoute: 'quickback',
  name: 'My App',
  companyName: 'My Company',
});

See Library Usage for the complete guide.

Next Steps

• Configuration — CMS and Account config reference
• Multi-Domain Architecture — Custom domains and hostname routing
• Environment Variables — Complete variable reference
• Feature Flags — Enable and disable features
• Auth Hooks — Run project code on signup, login, and session events
• Customization — Branding, labels, and theming