With Quickback

When using Account UI with a Quickback-compiled backend, set the auth route mode to quickback to match Quickback's API structure. This is the recommended setup for Quickback projects.

Setup

You can use Account UI with Quickback as either a standalone template or an npm library.

Option A: Template (Clone the Source)

1. Clone the Template

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

2. Set the Auth Route Mode

Configure Account UI to use Quickback's route conventions:

.env

# Use Quickback route mode
VITE_AUTH_ROUTE=quickback

# Your Quickback API URL
VITE_API_URL=https://api.example.com

# Where this Account UI is hosted
VITE_ACCOUNT_APP_URL=https://account.example.com

# Your main application URL (redirect after login)
VITE_APP_URL=https://app.example.com

3. Configure Your App

.env

# App identity
VITE_APP_NAME=My App
VITE_APP_TAGLINE=Build faster, ship sooner
VITE_COMPANY_NAME=My Company Inc.

# Organization routing
VITE_TENANT_URL_PATTERN=/organizations/{slug}

# Features (match your quickback.config.ts)
ENABLE_SIGNUP=true
ENABLE_ORGANIZATIONS=true
ENABLE_PASSKEYS=true
ENABLE_EMAIL_OTP=true
ENABLE_ADMIN=true

4. Deploy

npm run build
npx wrangler deploy

Option B: Library (npm install)

Install as a dependency in your existing React app:

npm install quickback-better-auth-account-ui

src/main.tsx

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 Inc.',
  tagline: 'Build faster, ship sooner',
});

// Render AuthApp inside your router

For a Cloudflare Worker, re-export the worker entry:

src/worker.ts

export { default } from 'quickback-better-auth-account-ui/worker';

See Library Usage for the complete guide.

How It Works

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

Path	Purpose	Examples
`/auth/v1/*`	Authentication	Login, signup, sessions, passkeys
`/api/v1/*`	Data API	Organizations, API keys
`/storage/v1/*`	File storage	Avatar uploads, file management

These paths match what the Quickback compiler generates in your backend's src/index.ts.

Architecture

A typical Quickback deployment has three services:

account.example.com     → Account UI (this app)
api.example.com         → Quickback-compiled API
app.example.com         → Your main application

The Account UI handles all authentication flows. After login, users are redirected to your main application at VITE_APP_URL. Organization-specific redirects use the VITE_TENANT_URL_PATTERN.

Matching Features to Config

Enable Account UI features that match your quickback.config.ts:

quickback/quickback.config.ts

export default defineConfig({
  features: ["organizations"],     // → ENABLE_ORGANIZATIONS=true
  providers: {
    auth: {
      name: "better-auth",
      config: {
        plugins: [
          "organization",           // → ENABLE_ORGANIZATIONS=true
          "admin",                  // → ENABLE_ADMIN=true
          "apiKey",                 // → API key UI available
          "passkey",                // → ENABLE_PASSKEYS=true
          "emailOtp",              // → ENABLE_EMAIL_OTP=true
          "deviceAuthorization",   // → CLI login flow available
        ],
      },
    },
  },
});

If your config doesn't include a plugin, disable the corresponding feature flag in Account UI to hide that section of the UI.

File Uploads

When your Quickback project includes R2 file storage, enable avatar uploads:

VITE_ENABLE_FILE_UPLOADS=true

This allows users to upload profile avatars via the storage API at /storage/v1/object/avatars/.

VITE_AUTH_ROUTE=quickback
VITE_API_URL=http://localhost:8787
VITE_ACCOUNT_APP_URL=http://localhost:5173
VITE_APP_URL=http://localhost:3000
DISABLE_EMAIL_STATUS_CHECK=true

Production

.env.production

VITE_AUTH_ROUTE=quickback
VITE_API_URL=https://api.example.com
VITE_ACCOUNT_APP_URL=https://account.example.com
VITE_APP_URL=https://app.example.com
ENABLE_EMAIL_VERIFICATION=true

Wrangler Configuration

For Cloudflare Workers deployment, set variables in wrangler.toml:

wrangler.toml

[vars]
VITE_AUTH_ROUTE = "quickback"
VITE_API_URL = "https://api.example.com"
VITE_ACCOUNT_APP_URL = "https://account.example.com"
VITE_APP_URL = "https://app.example.com"
VITE_APP_NAME = "My App"
VITE_TENANT_URL_PATTERN = "/organizations/{slug}"

Next Steps

Environment Variables — Complete variable reference
Customization — Branding, labels, and theming
Feature Flags — Enable and disable features
Worker Setup — Cloudflare Workers deployment details