Library Usage

Instead of cloning the template, you can install Account UI as an npm package. This gives you automatic updates via npm update while configuring the UI through setAppConfig().

When to use library mode

Use library mode when you want to embed Account UI into an existing React application without owning the source. For full control over the source code, use the standalone template instead.

Installation

npm install quickback-better-auth-account-ui

Peer Dependencies

Account UI expects these packages in your app:

npm install react react-dom react-router-dom @tanstack/react-query

Basic Setup

1. Import and Configure

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
import 'quickback-better-auth-account-ui/styles.css';

setAppConfig({
  authRoute: 'quickback',  // or 'better-auth' for standalone Better Auth
  name: 'My App',
  companyName: 'My Company Inc.',
  tagline: 'Build faster, ship sooner',
  description: 'My app description',
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <BrowserRouter>
      <AuthApp />
    </BrowserRouter>
  </React.StrictMode>
);

2. Set API URLs

The library reads API URLs from globalThis variables. Set these before importing the library:

src/main.tsx

// Set API URLs before auth-ui loads
(globalThis as any).__QUICKBACK_API_URL__ = 'https://api.example.com';
(globalThis as any).__QUICKBACK_APP_URL__ = 'https://account.example.com';

// Then import dynamically to ensure globals are set first
const { AuthApp, setAppConfig } = await import('quickback-better-auth-account-ui');
await import('quickback-better-auth-account-ui/styles.css');

Or with Vite environment variables:

src/main.tsx

(globalThis as any).__QUICKBACK_API_URL__ = import.meta.env.VITE_API_URL;
(globalThis as any).__QUICKBACK_APP_URL__ = import.meta.env.VITE_APP_URL;

Promise.all([
  import('quickback-better-auth-account-ui'),
  import('quickback-better-auth-account-ui/styles.css'),
]).then(([{ AuthApp, setAppConfig }]) => {
  setAppConfig({
    authRoute: 'quickback',
    name: import.meta.env.VITE_APP_NAME || 'My App',
    companyName: import.meta.env.VITE_COMPANY_NAME || 'My Company',
    tagline: import.meta.env.VITE_APP_TAGLINE || 'Welcome',
  });

  ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
      <BrowserRouter>
        <AuthApp />
      </BrowserRouter>
    </React.StrictMode>
  );
});

Cloudflare Worker

The library exports a Cloudflare Worker entry point for SPA routing and static asset serving:

src/worker.ts

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

Or extend it with custom logic:

src/worker.ts

import { createAuthWorker } from 'quickback-better-auth-account-ui/worker';

export default createAuthWorker();

Configuration via `setAppConfig()`

In library mode, all configuration happens through setAppConfig() instead of environment variables.

Auth Route Mode

setAppConfig({
  authRoute: 'quickback',    // Quickback API: /auth/v1, /api/v1, /storage/v1
  // or
  authRoute: 'better-auth',  // Better Auth default: /api/auth
});

Branding

setAppConfig({
  name: 'Acme SaaS',
  companyName: 'Acme Corporation',
  tagline: 'Build faster, ship sooner',
  description: 'The complete platform for modern web applications',
  branding: {
    primaryColor: '#3b82f6',
    logoUrl: '/logo.png',
    faviconUrl: '/favicon.ico',
  },
});

Labels and Messages

setAppConfig({
  labels: {
    organizations: 'Workspaces',
    terms: 'Terms and Conditions',
    privacy: 'Privacy Notice',
  },
  messages: {
    noOrganizations: "You haven't joined any workspaces yet.",
    createOrganization: 'Create Workspace',
  },
});

Routes

setAppConfig({
  routes: {
    public: {
      login: '/sign-in',
      signup: '/sign-up',
    },
    organizations: {
      list: '/workspaces',
      create: '/workspaces/new',
    },
  },
});

Password and Session

setAppConfig({
  auth: {
    passwordRequirements: {
      minLength: 12,
      requireSymbols: true,
    },
    sessionDuration: 7 * 24 * 60 * 60,  // 7 days
  },
});

See Customization for the full reference of all configurable options.

Exports

The library provides the following exports:

Main Entry (`quickback-better-auth-account-ui`)

Export	Type	Description
`AuthApp`	Component	The main React application component
`authClient`	Object	Pre-configured Better Auth client
`appConfig`	Object	Current app configuration
`setAppConfig`	Function	Set app configuration overrides
`createAppConfig`	Function	Create a new config object
`getApiBase`	Function	Get the current API base URL
`setApiBase`	Function	Override the API base URL
`getAuthApiUrl`	Function	Get the auth API URL
`getDataApiUrl`	Function	Get the data API URL
`getStorageApiUrl`	Function	Get the storage API URL

Styles (`quickback-better-auth-account-ui/styles.css`)

The compiled CSS for the Account UI. Must be imported for the UI to render correctly.

Worker (`quickback-better-auth-account-ui/worker`)

Export	Type	Description
`default`	Worker	Cloudflare Worker with SPA routing
`createAuthWorker`	Function	Factory for creating a worker instance

Custom Styles

Override styles by importing your CSS after the library styles:

import 'quickback-better-auth-account-ui/styles.css';
import './my-overrides.css';

my-overrides.css

:root {
  --primary: 59 130 246;
  --primary-foreground: 255 255 255;
}

Updating

Update to the latest version:

npm update quickback-better-auth-account-ui

The library follows semantic versioning. Check the changelog for breaking changes.

Next Steps

Customization — Full configuration reference
Feature Flags — Enable and disable features
Worker Setup — Deploy to Cloudflare Workers
With Quickback — Quickback-specific configuration

Library Usage

On this page