Quickback Account UI

A production-ready React application providing complete authentication and account management functionality. Works with any Better Auth backend or Quickback-compiled API.

Overview

Account UI is a standalone SPA that provides:

• Authentication flows - Login, signup, password reset, email verification
• Account management - Profile editing, password changes, session management
• Organizations - Multi-tenant organization management with roles and invitations
• Passkeys - WebAuthn/FIDO2 passwordless authentication
• Admin panel - User and subscription management
• API key management - Generate and manage API keys for programmatic access

Features

Authentication

• Email/password authentication with secure password requirements
• Passkey (WebAuthn) support for passwordless login
• Magic link authentication via email
• Email OTP verification
• Email verification flow
• Password reset with secure tokens
• Session management across devices

Account Management

• User profile editing with avatar upload
• Password management
• Device and session management
• Two-factor authentication setup
• Account deletion with confirmation

Organizations

• Multi-tenant organization support
• Role-based access control (owner, admin, member)
• Member invitation system
• Organization settings management
• Organization creation and deletion

Admin Features

• User management dashboard
• Subscription management
• User creation and deletion
• Password reset for users
• Session management
• Ban/unban users

Quick Start

Account UI can be consumed in two ways:

Option A: Standalone Template

Clone the repo and own the source — edit anything you want:

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

Configure environment variables, build, and deploy:

cp .env.example .env.development
npm run build
npx wrangler deploy

Option B: Library Import

Install as a dependency and get updates via npm update:

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 the Library Usage guide for full details.

Which Mode Should I Use?

Architecture

Standalone Mode

The Account UI runs as a standalone SPA that:

1. Runs separately from your main application
2. Communicates with your API backend via REST
3. Serves from its own subdomain (e.g., account.example.com)
4. Redirects users to your main app after authentication

Why standalone? Security isolation, reusability across apps, edge performance via Cloudflare, and independent maintenance.

Library Mode

When imported as a library, the Account UI becomes a component in your existing React app:

1. Renders inside your application's router
2. Shares your app's React and router context
3. Configured via setAppConfig() — no env files needed
4. Updated via npm update — no manual merging

Why library? Seamless integration, automatic updates, and simpler deployment when you already have a React app.

Configuration

Standalone (Template)

Since you own the source code, you can customize the Account UI by:

1. Environment variables — Set VITE_* variables for build-time configuration
2. Edit source directly — Modify src/config/app.ts for defaults, labels, messages, routes, and features
3. Runtime overrides — Call setAppConfig() in src/main.tsx for programmatic configuration

Library

When using as a library, configure entirely via setAppConfig():

import { setAppConfig } from 'quickback-better-auth-account-ui';

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

See the following guides for detailed configuration:

• Environment Variables - Complete list of all configuration options
• Feature Flags - Enable/disable features
• Customization - Branding, labels, and messaging
• Worker Setup - Cloudflare Worker configuration

Integration with Your App

Redirecting to Account UI

From your main application, redirect users to the Account UI for authentication:

// Redirect to login
window.location.href = 'https://account.example.com/login';

// Redirect to profile
window.location.href = 'https://account.example.com/profile';

// Redirect to organization
window.location.href = 'https://account.example.com/organizations/acme-corp';

Returning to Your App

After authentication, the Account UI can redirect users back to your application:

# Set the main app URL
VITE_APP_URL=https://app.example.com

# Optional: Set tenant URL pattern
VITE_TENANT_URL_PATTERN=/organizations/{slug}

When a user logs in, they'll be redirected to VITE_APP_URL. When they access an organization, they'll be sent to the tenant URL (e.g., https://app.example.com/organizations/acme-corp).

API Integration

The Account UI connects to your API backend. The API path structure depends on your auth route mode:

Better Auth Mode (default)

https://api.example.com/api/auth/sign-in/email
https://api.example.com/api/auth/sign-up/email
https://api.example.com/api/auth/get-session
https://api.example.com/api/auth/passkey/register

Quickback Mode

https://api.example.com/auth/v1/sign-in/email
https://api.example.com/auth/v1/sign-up/email
https://api.example.com/auth/v1/get-session
https://api.example.com/auth/v1/passkey/register

See Standalone Usage for Better Auth backends or With Quickback for Quickback-compiled backends.

Project Structure

my-account-app/
├── src/
│   ├── main.tsx              # App entry point
│   ├── App.tsx               # Router & routes
│   ├── worker.ts             # Cloudflare Worker entry
│   ├── auth/
│   │   └── authClient.ts     # Better Auth client
│   ├── config/
│   │   ├── app.ts            # App config, labels, messages, features
│   │   ├── features.ts       # Feature flag helpers
│   │   ├── routes.ts         # Route helpers
│   │   └── runtime.ts        # Runtime API URL resolution
│   ├── pages/                # Page components
│   ├── components/           # Shared UI components
│   ├── layouts/              # Auth & public layouts
│   └── lib/                  # API client, utilities
├── .env.example              # Environment template
├── wrangler.toml             # Cloudflare Worker config
├── vite.config.ts            # Vite build config
└── tailwind.config.ts        # Tailwind CSS config

Next Steps

• Standalone Usage - Use with any Better Auth backend (template mode)
• With Quickback - Use with a Quickback-compiled backend
• Library Usage - Import as an npm package into your existing React app
• Environment Variables - Configure your deployment
• Feature Flags - Enable optional features
• Customization - Match your brand
• Worker Setup - Deploy to Cloudflare