@quickback-dev/cli 0.17.1 → 0.31.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +17 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +28 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +24 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +46 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/docs/changelog.md +780 -1174
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
- package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
- package/dist/skill/docs/compiler/config/domains.md +44 -10
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +203 -1
- package/dist/skill/docs/compiler/definitions/actions.md +40 -7
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
- package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +11 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
- package/dist/skill/docs/stack/index.md +8 -4
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +780 -1174
- package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
- package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
- package/src/skill/docs/compiler/config/domains.md +44 -10
- package/src/skill/docs/compiler/config/output.md +1 -1
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +203 -1
- package/src/skill/docs/compiler/definitions/actions.md +40 -7
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
- package/src/skill/docs/compiler/getting-started/templates.md +58 -56
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +11 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/index.md +74 -0
- package/src/skill/docs/stack/index.md +8 -4
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- package/src/skill/docs/stack/account-ui/worker.md +0 -362
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
# Mappings
|
|
2
|
-
|
|
3
|
-
This page shows how each Quickback primitive maps to RLS policy SQL. The same `firewall` and `access` config used by the [Hono target](/compiler/targets/hono-api) generates these policies — no Supabase-specific re-authoring required.
|
|
4
|
-
|
|
5
|
-
## Schema → Tables
|
|
6
|
-
|
|
7
|
-
`defineTable({ schema })` compiles to a Drizzle PostgreSQL schema and a `CREATE TABLE` statement. RLS is enabled on the table by default:
|
|
8
|
-
|
|
9
|
-
```sql
|
|
10
|
-
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Firewall → `FOR ALL USING`
|
|
14
|
-
|
|
15
|
-
Firewall rules isolate data by tenant or owner. They become a single `FOR ALL USING` policy applied to every operation.
|
|
16
|
-
|
|
17
|
-
**Org-scoped:**
|
|
18
|
-
|
|
19
|
-
```typescript
|
|
20
|
-
firewall: [
|
|
21
|
-
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
22
|
-
]
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
```sql
|
|
26
|
-
CREATE POLICY "projects_firewall" ON projects FOR ALL
|
|
27
|
-
USING (organization_id = public.get_active_org_id());
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
**User-scoped:**
|
|
31
|
-
|
|
32
|
-
```typescript
|
|
33
|
-
firewall: [
|
|
34
|
-
{ field: 'userId', equals: 'ctx.userId' },
|
|
35
|
-
]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
```sql
|
|
39
|
-
CREATE POLICY "preferences_firewall" ON preferences FOR ALL
|
|
40
|
-
USING (user_id = auth.uid());
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
## Access → `FOR SELECT/INSERT/UPDATE/DELETE USING`
|
|
44
|
-
|
|
45
|
-
Access rules layer role-based checks on top of the firewall. Each operation gets its own policy.
|
|
46
|
-
|
|
47
|
-
```typescript
|
|
48
|
-
access: {
|
|
49
|
-
roles: ['admin', 'member'],
|
|
50
|
-
list: { roles: ['admin', 'member'] },
|
|
51
|
-
create: { roles: ['admin'] },
|
|
52
|
-
update: { roles: ['admin'] },
|
|
53
|
-
delete: { roles: ['admin'] },
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
```sql
|
|
58
|
-
CREATE POLICY "projects_select" ON projects FOR SELECT
|
|
59
|
-
USING (
|
|
60
|
-
organization_id = public.get_active_org_id()
|
|
61
|
-
AND public.has_any_role(ARRAY['admin', 'member'])
|
|
62
|
-
);
|
|
63
|
-
|
|
64
|
-
CREATE POLICY "projects_insert" ON projects FOR INSERT
|
|
65
|
-
WITH CHECK (
|
|
66
|
-
organization_id = public.get_active_org_id()
|
|
67
|
-
AND public.has_any_role(ARRAY['admin'])
|
|
68
|
-
);
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Defense in depth — anon deny
|
|
72
|
-
|
|
73
|
-
Every generated table gets an explicit deny policy for the `anon` role:
|
|
74
|
-
|
|
75
|
-
```sql
|
|
76
|
-
CREATE POLICY "projects_deny_anon" ON projects FOR ALL
|
|
77
|
-
TO anon
|
|
78
|
-
USING (false);
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
Unauthenticated requests are blocked at the database level even if a policy elsewhere is misconfigured.
|
|
82
|
-
|
|
83
|
-
## Helper functions
|
|
84
|
-
|
|
85
|
-
Quickback emits a set of helper functions in `0100_create_rls_helpers.sql` that the policies reference:
|
|
86
|
-
|
|
87
|
-
| Function | Purpose |
|
|
88
|
-
|----------|---------|
|
|
89
|
-
| `get_active_org_id()` | Returns the user's active organization from `user_sessions` |
|
|
90
|
-
| `has_any_role(roles[])` | Checks if the user has any of the listed roles in the active org |
|
|
91
|
-
| `has_org_role(role)` | Checks for a single specific role |
|
|
92
|
-
| `is_org_member()` | Checks org membership |
|
|
93
|
-
| `get_user_role()` | Returns the user's role in the active org |
|
|
94
|
-
|
|
95
|
-
These are used by the generated policies but you can also call them from views, triggers, or stored procedures.
|
|
96
|
-
|
|
97
|
-
## What does not compile
|
|
98
|
-
|
|
99
|
-
`defineActions()`, `views`, `masking`, and runtime `guards` do **not** become RLS — see [Limitations](/compiler/targets/supabase-rls/limitations).
|
|
@@ -1,88 +0,0 @@
|
|
|
1
|
-
# Setup
|
|
2
|
-
|
|
3
|
-
## Prerequisites
|
|
4
|
-
|
|
5
|
-
- A Supabase project (free tier is fine for development)
|
|
6
|
-
- The Supabase CLI installed: `npm install -g supabase`
|
|
7
|
-
- A Quickback project (`quickback create` or existing)
|
|
8
|
-
|
|
9
|
-
## 1. Configure the target
|
|
10
|
-
|
|
11
|
-
```typescript title="quickback/quickback.config.ts"
|
|
12
|
-
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
13
|
-
|
|
14
|
-
export default defineConfig({
|
|
15
|
-
name: "my-app",
|
|
16
|
-
providers: {
|
|
17
|
-
runtime: defineRuntime("supabase"),
|
|
18
|
-
database: defineDatabase("supabase"),
|
|
19
|
-
auth: defineAuth("supabase-auth"),
|
|
20
|
-
},
|
|
21
|
-
});
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
The `supabase-auth` provider tells Quickback to emit RLS policies that reference `auth.uid()` — Supabase's built-in JWT claim function — rather than the Better Auth equivalents used by the Neon target.
|
|
25
|
-
|
|
26
|
-
## 2. Compile
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
quickback compile
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
This generates:
|
|
33
|
-
|
|
34
|
-
```
|
|
35
|
-
supabase/
|
|
36
|
-
├── migrations/
|
|
37
|
-
│ ├── 0100_create_rls_helpers.sql # get_active_org_id(), has_any_role(), etc.
|
|
38
|
-
│ ├── 0101_create_rls_policies.sql # Per-table SELECT/INSERT/UPDATE/DELETE policies
|
|
39
|
-
│ └── 0102_create_audit_triggers.sql # Optional audit logging
|
|
40
|
-
src/
|
|
41
|
-
├── db/
|
|
42
|
-
│ └── schema.ts # Drizzle schema (typed access from your app)
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## 3. Apply migrations
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
supabase db push
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
Supabase applies the migrations to your remote project. RLS is enabled on every generated table and the deny-anon policy is installed.
|
|
52
|
-
|
|
53
|
-
## 4. Use from your app
|
|
54
|
-
|
|
55
|
-
Quickback for Supabase doesn't generate API routes. Your application code (PostgREST, Edge Functions, your own server) talks to Supabase as normal — the RLS policies are enforced beneath it.
|
|
56
|
-
|
|
57
|
-
```typescript
|
|
58
|
-
import { createClient } from '@supabase/supabase-js';
|
|
59
|
-
|
|
60
|
-
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
|
|
61
|
-
global: { headers: { Authorization: `Bearer ${userJwt}` } },
|
|
62
|
-
});
|
|
63
|
-
|
|
64
|
-
// RLS policies generated by Quickback enforce row-level access
|
|
65
|
-
const { data } = await supabase.from('projects').select('*');
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Updating the schema
|
|
69
|
-
|
|
70
|
-
Edit your `defineTable()` files, recompile, and push:
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
quickback compile
|
|
74
|
-
supabase db push
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
The compiler diffs against the previous compilation and emits a new migration only for what changed.
|
|
78
|
-
|
|
79
|
-
## Comparison with the Neon target
|
|
80
|
-
|
|
81
|
-
| | Supabase | Neon |
|
|
82
|
-
|---|----------|------|
|
|
83
|
-
| Auth function | `auth.uid()` | `auth.user_id()` |
|
|
84
|
-
| Auth provider | Supabase Auth | Better Auth + Neon Authorize |
|
|
85
|
-
| Users table | `auth.users` | `public.users` |
|
|
86
|
-
| API code generated | No | Yes (Hono routes) |
|
|
87
|
-
|
|
88
|
-
Both targets emit RLS policies. The difference is who issues the JWTs and where the application logic lives.
|
|
@@ -1,257 +0,0 @@
|
|
|
1
|
-
# Library Usage
|
|
2
|
-
|
|
3
|
-
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()`.
|
|
4
|
-
|
|
5
|
-
> **When to use library mode**
|
|
6
|
-
>
|
|
7
|
-
> 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](/stack/account-ui/standalone) instead.
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
## Installation
|
|
11
|
-
|
|
12
|
-
```bash
|
|
13
|
-
npm install quickback-better-auth-account-ui
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
### Peer Dependencies
|
|
17
|
-
|
|
18
|
-
Account UI expects these packages in your app:
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
npm install react react-dom react-router-dom @tanstack/react-query
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
## Basic Setup
|
|
25
|
-
|
|
26
|
-
### 1. Import and Configure
|
|
27
|
-
|
|
28
|
-
```tsx title="src/main.tsx"
|
|
29
|
-
import React from 'react';
|
|
30
|
-
import ReactDOM from 'react-dom/client';
|
|
31
|
-
import { BrowserRouter } from 'react-router-dom';
|
|
32
|
-
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
|
|
33
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
34
|
-
|
|
35
|
-
setAppConfig({
|
|
36
|
-
authRoute: 'quickback', // or 'better-auth' for standalone Better Auth
|
|
37
|
-
name: 'My App',
|
|
38
|
-
companyName: 'My Company Inc.',
|
|
39
|
-
tagline: 'Build faster, ship sooner',
|
|
40
|
-
description: 'My app description',
|
|
41
|
-
});
|
|
42
|
-
|
|
43
|
-
ReactDOM.createRoot(document.getElementById('root')!).render(
|
|
44
|
-
<React.StrictMode>
|
|
45
|
-
<BrowserRouter>
|
|
46
|
-
<AuthApp />
|
|
47
|
-
</BrowserRouter>
|
|
48
|
-
</React.StrictMode>
|
|
49
|
-
);
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
### 2. Set API URLs
|
|
53
|
-
|
|
54
|
-
The library reads API URLs from `globalThis` variables. Set these before importing the library:
|
|
55
|
-
|
|
56
|
-
```tsx title="src/main.tsx"
|
|
57
|
-
// Single catch-all: API + Account + CMS URLs are all derived from this origin.
|
|
58
|
-
(globalThis as any).__QUICKBACK_URL__ = 'https://secure.example.com';
|
|
59
|
-
(globalThis as any).__QUICKBACK_APP_URL__ = 'https://app.example.com';
|
|
60
|
-
|
|
61
|
-
// Then import dynamically to ensure globals are set first
|
|
62
|
-
const { AuthApp, setAppConfig } = await import('quickback-better-auth-account-ui');
|
|
63
|
-
await import('quickback-better-auth-account-ui/styles.css');
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
If your API lives on a different subdomain, set `__QUICKBACK_API_URL__` explicitly instead (or alongside) — it takes precedence over the catch-all:
|
|
67
|
-
|
|
68
|
-
```tsx
|
|
69
|
-
(globalThis as any).__QUICKBACK_URL__ = 'https://secure.example.com'; // catch-all
|
|
70
|
-
(globalThis as any).__QUICKBACK_API_URL__ = 'https://api.example.com'; // explicit override
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Or with Vite environment variables:
|
|
74
|
-
|
|
75
|
-
```tsx title="src/main.tsx"
|
|
76
|
-
(globalThis as any).__QUICKBACK_URL__ = import.meta.env.VITE_QUICKBACK_URL;
|
|
77
|
-
(globalThis as any).__QUICKBACK_API_URL__ = import.meta.env.VITE_QUICKBACK_API_URL;
|
|
78
|
-
(globalThis as any).__QUICKBACK_APP_URL__ = import.meta.env.VITE_QUICKBACK_APP_URL;
|
|
79
|
-
|
|
80
|
-
Promise.all([
|
|
81
|
-
import('quickback-better-auth-account-ui'),
|
|
82
|
-
import('quickback-better-auth-account-ui/styles.css'),
|
|
83
|
-
]).then(([{ AuthApp, setAppConfig }]) => {
|
|
84
|
-
setAppConfig({
|
|
85
|
-
authRoute: 'quickback',
|
|
86
|
-
name: import.meta.env.VITE_APP_NAME || 'My App',
|
|
87
|
-
companyName: import.meta.env.VITE_COMPANY_NAME || 'My Company',
|
|
88
|
-
tagline: import.meta.env.VITE_APP_TAGLINE || 'Welcome',
|
|
89
|
-
});
|
|
90
|
-
|
|
91
|
-
ReactDOM.createRoot(document.getElementById('root')!).render(
|
|
92
|
-
<React.StrictMode>
|
|
93
|
-
<BrowserRouter>
|
|
94
|
-
<AuthApp />
|
|
95
|
-
</BrowserRouter>
|
|
96
|
-
</React.StrictMode>
|
|
97
|
-
);
|
|
98
|
-
});
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## Cloudflare Worker
|
|
102
|
-
|
|
103
|
-
The library exports a Cloudflare Worker entry point for SPA routing and static asset serving:
|
|
104
|
-
|
|
105
|
-
```ts title="src/worker.ts"
|
|
106
|
-
export { default } from 'quickback-better-auth-account-ui/worker';
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Or extend it with custom logic:
|
|
110
|
-
|
|
111
|
-
```ts title="src/worker.ts"
|
|
112
|
-
import { createAuthWorker } from 'quickback-better-auth-account-ui/worker';
|
|
113
|
-
|
|
114
|
-
export default createAuthWorker();
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
## Configuration via `setAppConfig()`
|
|
118
|
-
|
|
119
|
-
In library mode, all configuration happens through `setAppConfig()` instead of environment variables.
|
|
120
|
-
|
|
121
|
-
### Auth Route Mode
|
|
122
|
-
|
|
123
|
-
```ts
|
|
124
|
-
setAppConfig({
|
|
125
|
-
authRoute: 'quickback', // Quickback API: /auth/v1, /api/v1, /storage/v1
|
|
126
|
-
// or
|
|
127
|
-
authRoute: 'better-auth', // Better Auth default: /api/auth
|
|
128
|
-
});
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
### Branding
|
|
132
|
-
|
|
133
|
-
```ts
|
|
134
|
-
setAppConfig({
|
|
135
|
-
name: 'Acme SaaS',
|
|
136
|
-
companyName: 'Acme Corporation',
|
|
137
|
-
tagline: 'Build faster, ship sooner',
|
|
138
|
-
description: 'The complete platform for modern web applications',
|
|
139
|
-
branding: {
|
|
140
|
-
primaryColor: '#3b82f6',
|
|
141
|
-
logoUrl: '/logo.png',
|
|
142
|
-
faviconUrl: '/favicon.ico',
|
|
143
|
-
},
|
|
144
|
-
});
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
### Labels and Messages
|
|
148
|
-
|
|
149
|
-
```ts
|
|
150
|
-
setAppConfig({
|
|
151
|
-
labels: {
|
|
152
|
-
organizations: 'Workspaces',
|
|
153
|
-
terms: 'Terms and Conditions',
|
|
154
|
-
privacy: 'Privacy Notice',
|
|
155
|
-
},
|
|
156
|
-
messages: {
|
|
157
|
-
noOrganizations: "You haven't joined any workspaces yet.",
|
|
158
|
-
createOrganization: 'Create Workspace',
|
|
159
|
-
},
|
|
160
|
-
});
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
### Routes
|
|
164
|
-
|
|
165
|
-
```ts
|
|
166
|
-
setAppConfig({
|
|
167
|
-
routes: {
|
|
168
|
-
public: {
|
|
169
|
-
login: '/sign-in',
|
|
170
|
-
signup: '/sign-up',
|
|
171
|
-
},
|
|
172
|
-
organizations: {
|
|
173
|
-
list: '/workspaces',
|
|
174
|
-
create: '/workspaces/new',
|
|
175
|
-
},
|
|
176
|
-
},
|
|
177
|
-
});
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
### Password and Session
|
|
181
|
-
|
|
182
|
-
```ts
|
|
183
|
-
setAppConfig({
|
|
184
|
-
auth: {
|
|
185
|
-
passwordRequirements: {
|
|
186
|
-
minLength: 12,
|
|
187
|
-
requireSymbols: true,
|
|
188
|
-
},
|
|
189
|
-
sessionDuration: 7 * 24 * 60 * 60, // 7 days
|
|
190
|
-
},
|
|
191
|
-
});
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
See [Customization](/stack/account-ui/customization) for the full reference of all configurable options.
|
|
195
|
-
|
|
196
|
-
## Exports
|
|
197
|
-
|
|
198
|
-
The library provides the following exports:
|
|
199
|
-
|
|
200
|
-
### Main Entry (`quickback-better-auth-account-ui`)
|
|
201
|
-
|
|
202
|
-
| Export | Type | Description |
|
|
203
|
-
|--------|------|-------------|
|
|
204
|
-
| `AuthApp` | Component | The main React application component |
|
|
205
|
-
| `authClient` | Object | Pre-configured Better Auth client |
|
|
206
|
-
| `appConfig` | Object | Current app configuration |
|
|
207
|
-
| `setAppConfig` | Function | Set app configuration overrides |
|
|
208
|
-
| `createAppConfig` | Function | Create a new config object |
|
|
209
|
-
| `getApiBase` | Function | Get the current API base URL |
|
|
210
|
-
| `setApiBase` | Function | Override the API base URL |
|
|
211
|
-
| `getAuthApiUrl` | Function | Get the auth API URL |
|
|
212
|
-
| `getDataApiUrl` | Function | Get the data API URL |
|
|
213
|
-
| `getStorageApiUrl` | Function | Get the storage API URL |
|
|
214
|
-
|
|
215
|
-
### Styles (`quickback-better-auth-account-ui/styles.css`)
|
|
216
|
-
|
|
217
|
-
The compiled CSS for the Account UI. Must be imported for the UI to render correctly.
|
|
218
|
-
|
|
219
|
-
### Worker (`quickback-better-auth-account-ui/worker`)
|
|
220
|
-
|
|
221
|
-
| Export | Type | Description |
|
|
222
|
-
|--------|------|-------------|
|
|
223
|
-
| `default` | Worker | Cloudflare Worker with SPA routing |
|
|
224
|
-
| `createAuthWorker` | Function | Factory for creating a worker instance |
|
|
225
|
-
|
|
226
|
-
## Custom Styles
|
|
227
|
-
|
|
228
|
-
Override styles by importing your CSS after the library styles:
|
|
229
|
-
|
|
230
|
-
```ts
|
|
231
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
232
|
-
import './my-overrides.css';
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
```css title="my-overrides.css"
|
|
236
|
-
:root {
|
|
237
|
-
--primary: 59 130 246;
|
|
238
|
-
--primary-foreground: 255 255 255;
|
|
239
|
-
}
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
## Updating
|
|
243
|
-
|
|
244
|
-
Update to the latest version:
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
npm update quickback-better-auth-account-ui
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
The library follows semantic versioning. Check the [changelog](https://github.com/Kardoe-com/quickback-better-auth-account-ui/releases) for breaking changes.
|
|
251
|
-
|
|
252
|
-
## Next Steps
|
|
253
|
-
|
|
254
|
-
- **[Customization](/stack/account-ui/customization)** — Full configuration reference
|
|
255
|
-
- **[Feature Flags](/stack/account-ui/features)** — Enable and disable features
|
|
256
|
-
- **[Worker Setup](/stack/account-ui/worker)** — Deploy to Cloudflare Workers
|
|
257
|
-
- **[With Quickback](/stack/account-ui/with-quickback)** — Quickback-specific configuration
|
|
@@ -1,149 +0,0 @@
|
|
|
1
|
-
# Standalone Usage
|
|
2
|
-
|
|
3
|
-
Account UI can be used with **any Better Auth-powered backend**, not just Quickback-compiled projects. This makes it a drop-in authentication frontend for any app using Better Auth.
|
|
4
|
-
|
|
5
|
-
> **Prefer npm install?**
|
|
6
|
-
>
|
|
7
|
-
> If you'd rather import Account UI as a library into an existing React app instead of cloning the template, see [Library Usage](/stack/account-ui/library-usage).
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
## Requirements
|
|
11
|
-
|
|
12
|
-
- A backend running [Better Auth](https://better-auth.com) with API endpoints
|
|
13
|
-
- Node.js 18+ and npm/pnpm/bun
|
|
14
|
-
- A Cloudflare account (for deployment)
|
|
15
|
-
|
|
16
|
-
## Setup
|
|
17
|
-
|
|
18
|
-
### 1. Clone or Install the Account UI
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
|
|
22
|
-
cd my-account-app
|
|
23
|
-
npm install
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
### 2. Configure the Auth Route Mode
|
|
27
|
-
|
|
28
|
-
The key difference from Quickback mode is the `VITE_AUTH_ROUTE` variable. Set it to `better-auth` to use Better Auth's default API paths:
|
|
29
|
-
|
|
30
|
-
```bash title=".env"
|
|
31
|
-
# Auth route mode — use 'better-auth' for standalone
|
|
32
|
-
VITE_AUTH_ROUTE=better-auth
|
|
33
|
-
|
|
34
|
-
# Your Better Auth backend URL (single catch-all — see below)
|
|
35
|
-
VITE_QUICKBACK_URL=https://secure.example.com
|
|
36
|
-
|
|
37
|
-
# Where this Account UI is hosted
|
|
38
|
-
VITE_ACCOUNT_APP_URL=https://account.example.com
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
`VITE_QUICKBACK_URL` is the recommended one-variable setup. If your API lives on a separate subdomain, set `VITE_QUICKBACK_API_URL` explicitly — it takes precedence.
|
|
42
|
-
|
|
43
|
-
This configures the auth client to use `/api/auth` as the base path (Better Auth's default), instead of Quickback's `/auth/v1`.
|
|
44
|
-
|
|
45
|
-
### 3. Configure Your App
|
|
46
|
-
|
|
47
|
-
```bash title=".env"
|
|
48
|
-
# App identity
|
|
49
|
-
VITE_APP_NAME=My App
|
|
50
|
-
VITE_APP_TAGLINE=Welcome to My App
|
|
51
|
-
|
|
52
|
-
# Redirect after login
|
|
53
|
-
VITE_QUICKBACK_APP_URL=https://app.example.com
|
|
54
|
-
|
|
55
|
-
# Feature flags
|
|
56
|
-
ENABLE_SIGNUP=true
|
|
57
|
-
ENABLE_ORGANIZATIONS=true
|
|
58
|
-
ENABLE_PASSKEY=true
|
|
59
|
-
ENABLE_EMAIL_OTP=true
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
See [Environment Variables](/stack/account-ui/environment-variables) for the complete reference.
|
|
63
|
-
|
|
64
|
-
### 4. Build and Deploy
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
npm run build
|
|
68
|
-
npx wrangler deploy
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Auth Route Modes
|
|
72
|
-
|
|
73
|
-
Account UI supports three routing modes, controlled by `VITE_AUTH_ROUTE`:
|
|
74
|
-
|
|
75
|
-
| Mode | Value | Auth Path | Data Path | Storage Path |
|
|
76
|
-
|------|-------|-----------|-----------|--------------|
|
|
77
|
-
| Better Auth | `better-auth` | `/api/auth` | — | — |
|
|
78
|
-
| Quickback | `quickback` | `/auth/v1` | `/api/v1` | `/storage/v1` |
|
|
79
|
-
| Custom | `custom` | Custom | Custom | Custom |
|
|
80
|
-
|
|
81
|
-
### Better Auth Mode (Default)
|
|
82
|
-
|
|
83
|
-
Routes all auth requests to `/api/auth/*` — the standard Better Auth convention:
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
VITE_AUTH_ROUTE=better-auth
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### Custom Mode
|
|
90
|
-
|
|
91
|
-
For non-standard setups, use custom mode with explicit paths:
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
VITE_AUTH_ROUTE=custom
|
|
95
|
-
VITE_AUTH_BASE_PATH=/my-auth
|
|
96
|
-
VITE_DATA_BASE_PATH=/my-api
|
|
97
|
-
VITE_STORAGE_BASE_PATH=/my-storage
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
## Backend Requirements
|
|
101
|
-
|
|
102
|
-
Your Better Auth backend must have the following plugins enabled for full Account UI functionality:
|
|
103
|
-
|
|
104
|
-
| Feature | Required Plugin | Required For |
|
|
105
|
-
|---------|----------------|--------------|
|
|
106
|
-
| Organizations | `organization` | Multi-tenant org management |
|
|
107
|
-
| Admin panel | `admin` | User management dashboard |
|
|
108
|
-
| API keys | `apiKey` | API key generation UI |
|
|
109
|
-
| Passkeys | `@better-auth/passkey` | WebAuthn authentication |
|
|
110
|
-
| Email OTP | `emailOTP` | One-time password login |
|
|
111
|
-
| CLI login | `deviceAuthorization` | `quickback login` flow |
|
|
112
|
-
|
|
113
|
-
Only enable the features that match your backend's plugin configuration. Disable features for plugins you haven't installed:
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
# If your backend doesn't have the organization plugin:
|
|
117
|
-
ENABLE_ORGANIZATIONS=false
|
|
118
|
-
|
|
119
|
-
# If you haven't set up passkeys:
|
|
120
|
-
ENABLE_PASSKEYS=false
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
## CORS Configuration
|
|
124
|
-
|
|
125
|
-
Your Better Auth backend must allow requests from the Account UI's domain. Configure CORS to include:
|
|
126
|
-
|
|
127
|
-
```typescript
|
|
128
|
-
// In your Better Auth config
|
|
129
|
-
trustedOrigins: [
|
|
130
|
-
"https://account.example.com", // Account UI domain
|
|
131
|
-
],
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
## Differences from Quickback Mode
|
|
135
|
-
|
|
136
|
-
| Aspect | Standalone | With Quickback |
|
|
137
|
-
|--------|-----------|----------------|
|
|
138
|
-
| Auth routes | `/api/auth/*` | `/auth/v1/*` |
|
|
139
|
-
| Data API | Not used | `/api/v1/*` |
|
|
140
|
-
| Storage API | Not used | `/storage/v1/*` |
|
|
141
|
-
| File uploads | Manual setup | Auto-configured |
|
|
142
|
-
| Backend | Any Better Auth app | Quickback-compiled |
|
|
143
|
-
|
|
144
|
-
## Next Steps
|
|
145
|
-
|
|
146
|
-
- [Environment Variables](/stack/account-ui/environment-variables) — Complete configuration reference
|
|
147
|
-
- [Customization](/stack/account-ui/customization) — Branding, labels, and theming
|
|
148
|
-
- [Worker Setup](/stack/account-ui/worker) — Cloudflare Workers deployment
|
|
149
|
-
- [Feature Flags](/stack/account-ui/features) — Enable and disable features
|