@quickback-dev/cli 0.18.0 → 0.34.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 +25 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +17 -0
- package/dist/commands/migrations.d.ts.map +1 -0
- package/dist/commands/migrations.js +328 -0
- package/dist/commands/migrations.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +33 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +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 +39 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +73 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +22 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +1118 -1
- package/dist/skill/docs/compiler/config/domains.md +70 -10
- package/dist/skill/docs/compiler/config/index.md +74 -3
- 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/single-tenant.md +1 -1
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +357 -3
- package/dist/skill/docs/compiler/definitions/actions.md +85 -8
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- 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 +2 -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/admin.md +2 -2
- 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/hooks.md +4 -0
- 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/aws-ses.md +60 -0
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +1057 -0
- package/src/skill/docs/compiler/config/domains.md +26 -0
- package/src/skill/docs/compiler/config/index.md +74 -3
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/single-tenant.md +1 -1
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +357 -3
- package/src/skill/docs/compiler/definitions/actions.md +85 -8
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- 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 +2 -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/admin.md +2 -2
- 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/hooks.md +4 -0
- 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/aws-ses.md +60 -0
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/src/skill/docs/stack/auth/plugins/index.md +32 -0
- 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,62 +1,44 @@
|
|
|
1
1
|
# Quickback Compiler
|
|
2
2
|
|
|
3
|
-
The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits production
|
|
3
|
+
The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits a production Hono application for the **Quickback Stack** on Cloudflare.
|
|
4
4
|
|
|
5
5
|
```
|
|
6
|
-
defineTable() ─┐
|
|
7
|
-
├─► quickback compile
|
|
8
|
-
defineActions()─┘
|
|
6
|
+
defineTable() ─┐
|
|
7
|
+
├─► quickback compile ─► Hono API on Cloudflare
|
|
8
|
+
defineActions()─┘ (D1 or Neon)
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
The same definitions, the same DSL — pick the target that fits where you're deploying.
|
|
12
|
-
|
|
13
11
|
## What the compiler does
|
|
14
12
|
|
|
15
13
|
When you run `quickback compile`, it:
|
|
16
14
|
|
|
17
15
|
1. **Reads your definitions** — every `defineTable()`, `defineActions()`, and `defineConfig()` in your project
|
|
18
16
|
2. **Validates security** — firewall, access, guards, and masking are checked for consistency
|
|
19
|
-
3. **Generates
|
|
17
|
+
3. **Generates output** — Hono routes + middleware + types + OpenAPI spec + MCP server + security artifacts
|
|
20
18
|
4. **Emits database migrations** — runs `drizzle-kit generate` for schema changes
|
|
21
19
|
|
|
22
20
|
```
|
|
23
21
|
quickback/
|
|
24
|
-
├── quickback.config.ts # Compiler configuration (
|
|
22
|
+
├── quickback.config.ts # Compiler configuration (providers, options)
|
|
25
23
|
└── features/
|
|
26
24
|
└── jobs/
|
|
27
25
|
├── jobs.ts # defineTable(...)
|
|
28
26
|
└── actions.ts # defineActions(...)
|
|
29
27
|
```
|
|
30
28
|
|
|
31
|
-
##
|
|
32
|
-
|
|
33
|
-
### [Quickback for Hono API](/compiler/targets/hono-api)
|
|
29
|
+
## The target: Hono on Cloudflare
|
|
34
30
|
|
|
35
|
-
|
|
31
|
+
[Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL via Hyperdrive.
|
|
36
32
|
|
|
37
33
|
```typescript
|
|
38
34
|
providers: {
|
|
39
35
|
runtime: defineRuntime('cloudflare'),
|
|
40
|
-
database: defineDatabase('cloudflare-d1'),
|
|
36
|
+
database: defineDatabase('cloudflare-d1'), // or 'neon'
|
|
41
37
|
auth: defineAuth('better-auth'),
|
|
42
38
|
}
|
|
43
39
|
```
|
|
44
40
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your existing app code.
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
providers: {
|
|
51
|
-
runtime: defineRuntime('supabase'),
|
|
52
|
-
database: defineDatabase('supabase'),
|
|
53
|
-
auth: defineAuth('supabase-auth'),
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
## The shared core
|
|
58
|
-
|
|
59
|
-
Whichever target you pick, the **input language is the same**:
|
|
41
|
+
## The DSL
|
|
60
42
|
|
|
61
43
|
- **[Definitions](/compiler/definitions)** — Schema, Firewall, Access, Guards, Masking, Views, Actions
|
|
62
44
|
- **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
|
|
@@ -73,13 +55,12 @@ You don't run the compiler binary locally — it runs as a hosted service:
|
|
|
73
55
|
|
|
74
56
|
1. **Define resources** in `quickback/features/`
|
|
75
57
|
2. **Compile** with `quickback compile`
|
|
76
|
-
3. **Apply migrations**
|
|
77
|
-
4. **Test locally** with `
|
|
78
|
-
5. **Deploy** with `
|
|
58
|
+
3. **Apply migrations** with `wrangler d1 migrations apply`
|
|
59
|
+
4. **Test locally** with `wrangler dev`
|
|
60
|
+
5. **Deploy** with `wrangler deploy`
|
|
79
61
|
|
|
80
62
|
## Next steps
|
|
81
63
|
|
|
82
64
|
- [Getting Started](/compiler/getting-started) — Create your first project
|
|
83
|
-
- [Definitions](/compiler/definitions) — The
|
|
84
|
-
- [Quickback for Hono API](/compiler/targets/hono-api) —
|
|
85
|
-
- [Quickback for Supabase](/compiler/targets/supabase-rls) — Compile to RLS policies
|
|
65
|
+
- [Definitions](/compiler/definitions) — The DSL
|
|
66
|
+
- [Quickback for Hono API](/compiler/targets/hono-api) — Generated output reference
|
|
@@ -90,5 +90,4 @@ Your `wrangler.toml` needs these bindings:
|
|
|
90
90
|
|
|
91
91
|
- [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Step-by-step setup guide with full wrangler.toml configuration
|
|
92
92
|
- [D1 Database](/compiler/targets/hono-api/database/d1) — D1 setup, multi-database pattern, and security architecture
|
|
93
|
-
- [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL
|
|
94
|
-
- [Supabase Integration](/compiler/targets/supabase-rls) — Alternative: Supabase with RLS
|
|
93
|
+
- [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL via Hyperdrive
|
|
@@ -141,4 +141,3 @@ src/
|
|
|
141
141
|
|
|
142
142
|
- [D1](/compiler/targets/hono-api/database/d1) — SQLite at the edge
|
|
143
143
|
- [Providers](/compiler/config/providers) — All database provider options
|
|
144
|
-
- [Quickback for Supabase](/compiler/targets/supabase-rls) — A different Postgres+RLS path that uses Supabase Auth instead of Better Auth
|
|
@@ -99,6 +99,25 @@ All actions (both standalone and record-based) receive a **scoped `db`** instanc
|
|
|
99
99
|
- Tables with `deletedAt` — soft delete filter (`WHERE deletedAt IS NULL`)
|
|
100
100
|
- `INSERT` operations auto-inject `organizationId` and `ownerId` from context
|
|
101
101
|
|
|
102
|
+
#### `userId` vs `ownerId` on feature tables
|
|
103
|
+
|
|
104
|
+
Use `ownerId` (not `userId`) for the row-owner column on a feature table. The compiler:
|
|
105
|
+
|
|
106
|
+
- Auto-firewalls reads on `ownerId` (`WHERE ownerId = ctx.userId`).
|
|
107
|
+
- Auto-stamps `ownerId` on insert from `ctx.userId`.
|
|
108
|
+
- Treats a `userId` column on a feature table as **informational** — almost always "a user this row references" (member, contact, invitee), not "the row owner."
|
|
109
|
+
|
|
110
|
+
A `userId` column on a feature table emits a compile-time warning. To resolve it:
|
|
111
|
+
|
|
112
|
+
- **Rename to `ownerId`** if the column controls access (most common case).
|
|
113
|
+
- **Rename to `linkedUserId`** (or similar) if the column is informational — explicit naming prevents future confusion.
|
|
114
|
+
- **Declare explicit firewall** if `userId` really is the access column on that table:
|
|
115
|
+
```ts
|
|
116
|
+
firewall: [{ field: 'userId', equals: 'ctx.userId' }]
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) use `userId` by convention. Those are not feature tables and don't pass through the auto-firewall — the warning only fires on resources you define in your `quickback/` folder.
|
|
120
|
+
|
|
102
121
|
```typescript
|
|
103
122
|
// Your handler receives a scoped db — no manual filtering needed
|
|
104
123
|
execute: async ({ db, ctx, input }) => {
|
|
@@ -264,7 +264,7 @@ rollback.
|
|
|
264
264
|
|
|
265
265
|
| Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
|
|
266
266
|
|----------|----------|-----------|----------------------|----------|
|
|
267
|
-
| `PATCH /batch` (update) |
|
|
267
|
+
| `PATCH /batch` (update) | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
|
|
268
268
|
| `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
|
|
269
269
|
| `PATCH /batch` (update) | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — D1 has no `db.transaction`. Records before the failure stay committed. |
|
|
270
270
|
| `PUT /batch` (upsert) | tx-supporting | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
|
|
@@ -1,47 +1,19 @@
|
|
|
1
1
|
# Compile Targets
|
|
2
2
|
|
|
3
|
-
The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits production
|
|
3
|
+
The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits a production Hono application for the **Quickback Stack** on Cloudflare.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## [Quickback for Hono API](/compiler/targets/hono-api)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
|
|
7
|
+
Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server, security artifacts. Pair with **Cloudflare D1** for SQLite at the edge or **Neon** for full PostgreSQL via Hyperdrive.
|
|
10
8
|
|
|
11
9
|
```typescript
|
|
12
10
|
providers: {
|
|
13
11
|
runtime: defineRuntime('cloudflare'),
|
|
14
|
-
database: defineDatabase('cloudflare-d1'),
|
|
12
|
+
database: defineDatabase('cloudflare-d1'), // or 'neon'
|
|
15
13
|
auth: defineAuth('better-auth'),
|
|
16
14
|
}
|
|
17
15
|
```
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
### [Quickback for Supabase](/compiler/targets/supabase-rls)
|
|
22
|
-
|
|
23
|
-
Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your application code.
|
|
24
|
-
|
|
25
|
-
```typescript
|
|
26
|
-
providers: {
|
|
27
|
-
runtime: defineRuntime('supabase'),
|
|
28
|
-
database: defineDatabase('supabase'),
|
|
29
|
-
auth: defineAuth('supabase-auth'),
|
|
30
|
-
}
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
Use this target when you're already on Supabase and want a typed DSL for RLS.
|
|
34
|
-
|
|
35
|
-
## At a glance
|
|
36
|
-
|
|
37
|
-
| | Hono API | Supabase RLS |
|
|
38
|
-
|---|----------|--------------|
|
|
39
|
-
| What's generated | Routes, middleware, types, OpenAPI, MCP, RLS (Neon only) | RLS policies + helper functions only |
|
|
40
|
-
| Database | Cloudflare D1 or Neon Postgres | Supabase Postgres |
|
|
41
|
-
| Auth | Better Auth | Supabase Auth |
|
|
42
|
-
| Application code | Compiler-generated | You write your own |
|
|
43
|
-
| Deployment | `wrangler deploy` (or any Hono runtime) | `supabase db push` |
|
|
44
|
-
|
|
45
|
-
## The shared core
|
|
17
|
+
## The DSL
|
|
46
18
|
|
|
47
|
-
|
|
19
|
+
See [Definitions](/compiler/definitions) for the schema + security DSL — the same input drives every output the compiler emits.
|
package/dist/skill/docs/index.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Quickback Documentation
|
|
2
2
|
|
|
3
|
-
Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API
|
|
3
|
+
Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API running on Cloudflare Workers, plus the Account UI and CMS that ride alongside it. The Quickback Stack is the Supabase alternative on Cloudflare.
|
|
4
4
|
|
|
5
5
|
## Quick start
|
|
6
6
|
|
|
@@ -49,12 +49,9 @@ Request → Firewall → Access → Guards → Masking → Response
|
|
|
49
49
|
|
|
50
50
|
### Quickback Compiler
|
|
51
51
|
|
|
52
|
-
[**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to
|
|
52
|
+
[**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to a complete Hono application on Cloudflare:
|
|
53
53
|
|
|
54
54
|
- **[Quickback for Hono API](/compiler/targets/hono-api)** — A complete Hono application on Cloudflare D1 or Neon, with CRUD, batch endpoints, OpenAPI, and an MCP server.
|
|
55
|
-
- **[Quickback for Supabase](/compiler/targets/supabase-rls)** — PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
|
|
56
|
-
|
|
57
|
-
The same `defineTable()` definitions work for both targets.
|
|
58
55
|
|
|
59
56
|
**Start here:**
|
|
60
57
|
- **[Getting Started](/compiler/getting-started)** — Create your first project
|
|
@@ -1,18 +1,6 @@
|
|
|
1
1
|
# Customization
|
|
2
2
|
|
|
3
|
-
Customize the Account UI to match your brand and messaging.
|
|
4
|
-
|
|
5
|
-
**Standalone (template):** Configure via environment variables, edit `src/config/app.ts` directly, or use `setAppConfig()` for runtime overrides.
|
|
6
|
-
|
|
7
|
-
**Library (npm):** Configure entirely via `setAppConfig()`. Import it from `quickback-better-auth-account-ui` instead of `@/config/app`.
|
|
8
|
-
|
|
9
|
-
> **Library imports**
|
|
10
|
-
>
|
|
11
|
-
> All `setAppConfig` examples below use the standalone import path (`@/config/app`). If you're using library mode, replace with:
|
|
12
|
-
> ```ts
|
|
13
|
-
> import { setAppConfig } from 'quickback-better-auth-account-ui';
|
|
14
|
-
> ```
|
|
15
|
-
|
|
3
|
+
Customize the Account UI to match your brand and messaging. Branding is driven by the `account` block in `quickback.config.ts` and the environment variables the compiler bakes in at build time.
|
|
16
4
|
|
|
17
5
|
## Branding
|
|
18
6
|
|
|
@@ -373,6 +361,6 @@ import './custom-styles.css'; // Your overrides
|
|
|
373
361
|
|
|
374
362
|
## Next Steps
|
|
375
363
|
|
|
376
|
-
- **[
|
|
364
|
+
- **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles your customized UI
|
|
377
365
|
- **[Environment Variables](/stack/account-ui/environment-variables)** - Complete configuration reference
|
|
378
366
|
- **[Feature Flags](/stack/account-ui/features)** - Enable/disable features
|
|
@@ -167,6 +167,11 @@ VITE_ENABLE_FILE_UPLOADS=false
|
|
|
167
167
|
```bash
|
|
168
168
|
# Enable multi-tenant organizations (default: true)
|
|
169
169
|
ENABLE_ORGANIZATIONS=true
|
|
170
|
+
|
|
171
|
+
# Enable Teams (sub-groups within an organization) (default: false)
|
|
172
|
+
# Auto-set to true when the BA config has organization({ teams: { enabled: true } }).
|
|
173
|
+
# When false the Teams tab is hidden and the auth client doesn't expose team APIs.
|
|
174
|
+
VITE_ENABLE_ORG_TEAMS=false
|
|
170
175
|
```
|
|
171
176
|
|
|
172
177
|
### Admin Features
|
|
@@ -218,6 +223,7 @@ ENABLE_PASSKEY=true
|
|
|
218
223
|
ENABLE_EMAIL_OTP=true
|
|
219
224
|
ENABLE_PASSWORD=false
|
|
220
225
|
ENABLE_ORGANIZATIONS=true
|
|
226
|
+
VITE_ENABLE_ORG_TEAMS=true
|
|
221
227
|
ENABLE_ADMIN=true
|
|
222
228
|
VITE_ENABLE_FILE_UPLOADS=true
|
|
223
229
|
DISABLE_EMAIL_STATUS_CHECK=false
|
|
@@ -322,4 +328,4 @@ Check the browser console for configuration warnings.
|
|
|
322
328
|
|
|
323
329
|
- **[Feature Flags](/stack/account-ui/features)** - Detailed feature configuration
|
|
324
330
|
- **[Customization](/stack/account-ui/customization)** - Customize labels and messages
|
|
325
|
-
- **[
|
|
331
|
+
- **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles Account UI
|
|
@@ -32,10 +32,10 @@ When `auth.admin` is `false` (the default), admin routes are excluded from the S
|
|
|
32
32
|
|
|
33
33
|
The admin panel is restricted to users with `role: "admin"` on their Better Auth user record. Non-admin users are redirected away from `/admin`.
|
|
34
34
|
|
|
35
|
-
To grant admin access to a user, use the Better Auth admin
|
|
35
|
+
To grant admin access to a user, use the Better Auth admin plugin:
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
curl -X POST https://api.example.com/
|
|
38
|
+
curl -X POST https://api.example.com/auth/v1/admin/set-role \
|
|
39
39
|
-H "Authorization: Bearer $TOKEN" \
|
|
40
40
|
-H "Content-Type: application/json" \
|
|
41
41
|
-d '{ "userId": "user_123", "role": "admin" }'
|
|
@@ -13,9 +13,7 @@ account: {
|
|
|
13
13
|
}
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` into the Account SPA's
|
|
17
|
-
build env. For standalone Account UI deployments (built outside the
|
|
18
|
-
compiler), set `VITE_ENABLE_FILE_UPLOADS=true` in `.env` directly.
|
|
16
|
+
The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` into the Account SPA's build env.
|
|
19
17
|
|
|
20
18
|
## Upload Flow
|
|
21
19
|
|
|
@@ -27,7 +25,7 @@ compiler), set `VITE_ENABLE_FILE_UPLOADS=true` in `.env` directly.
|
|
|
27
25
|
|
|
28
26
|
## Requirements
|
|
29
27
|
|
|
30
|
-
- `account.fileUploads: true`
|
|
28
|
+
- `account.fileUploads: true`
|
|
31
29
|
- R2 bucket or S3-compatible storage configured
|
|
32
30
|
- Upload endpoints available in your API
|
|
33
31
|
|
|
@@ -288,4 +288,4 @@ DISABLE_EMAIL_STATUS_CHECK=true # Allow test emails
|
|
|
288
288
|
|
|
289
289
|
- **[Environment Variables](/stack/account-ui/environment-variables)** - Complete variable reference
|
|
290
290
|
- **[Customization](/stack/account-ui/customization)** - Customize UI text and labels
|
|
291
|
-
- **[
|
|
291
|
+
- **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds Account UI into your Worker
|
|
@@ -1,27 +1,47 @@
|
|
|
1
1
|
# Organizations
|
|
2
2
|
|
|
3
|
-
Account UI provides a complete organization management interface when `
|
|
3
|
+
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
|
|
4
4
|
|
|
5
5
|
## Organization CRUD
|
|
6
6
|
|
|
7
|
-
- Create new organizations
|
|
8
|
-
- Update
|
|
9
|
-
- Delete organizations (owner
|
|
7
|
+
- Create new organizations, with `checkSlug` debounce on the slug field
|
|
8
|
+
- Update name, **slug** (rename navigates to the new URL), **metadata** (JSON object), and logo
|
|
9
|
+
- Delete organizations — gated on the `organization:delete` permission (default: owner)
|
|
10
10
|
|
|
11
11
|
## Member Management
|
|
12
12
|
|
|
13
|
-
- Invite members by email
|
|
13
|
+
- Invite members by email (with an optional team picker when teams are enabled)
|
|
14
14
|
- Assign roles: **owner**, **admin**, **member**
|
|
15
|
-
-
|
|
16
|
-
-
|
|
15
|
+
- Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
|
|
16
|
+
- Leave the organization
|
|
17
|
+
|
|
18
|
+
> **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above."
|
|
17
19
|
|
|
18
20
|
## Invitations
|
|
19
21
|
|
|
20
|
-
- Pending invitation list
|
|
21
|
-
- Resend
|
|
22
|
-
-
|
|
22
|
+
- Pending invitation list, per organization
|
|
23
|
+
- Resend, cancel (per-org), accept, and reject (per-user)
|
|
24
|
+
- Pending invites across organizations land on the user's `/dashboard`
|
|
25
|
+
- Invitations carry an optional `teamId` when teams are enabled — the invitee joins that team on accept
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
## Teams
|
|
28
|
+
|
|
29
|
+
Set `organization({ teams: { enabled: true } })` in your Better Auth config. The compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the SPA exposes:
|
|
30
|
+
|
|
31
|
+
- **Teams tab** on each organization, split into "Your teams" and "Other teams"
|
|
32
|
+
- **Team detail** page with member roster, add/remove members
|
|
33
|
+
- **Active-team picker** in the organization header — switches `session.activeTeamId` via `setActiveTeam`, so server-side handlers can scope by team
|
|
34
|
+
- **Team-aware invitations** — when sending an invite, optionally pick a team; the member is added on accept
|
|
35
|
+
|
|
36
|
+
Per-team actions (create / rename / delete / add-member / remove-member) gate on the `team:create`, `team:update`, and `team:delete` permissions from Better Auth's default statements.
|
|
37
|
+
|
|
38
|
+
## Permission-aware UI
|
|
39
|
+
|
|
40
|
+
Account UI uses Better Auth's `checkRolePermission` API instead of hardcoded role checks. The `OrganizationContext` exposes a `can(resource, action)` helper that handles the default statements (`organization`, `member`, `invitation`, `team`, `ac`) and respects any custom roles you've registered via the BA `ac` option.
|
|
41
|
+
|
|
42
|
+
Multi-role users — Better Auth stores multiple roles as a comma-separated string — are handled by checking each role independently; the action is allowed if any one of them grants it.
|
|
43
|
+
|
|
44
|
+
This means projects that ship custom roles get a UI that matches what their server actually authorizes, without modifying the Account SPA.
|
|
25
45
|
|
|
26
46
|
## Related
|
|
27
47
|
|
|
@@ -12,6 +12,7 @@ quickback/
|
|
|
12
12
|
after-user-create.ts
|
|
13
13
|
before-user-create.ts
|
|
14
14
|
after-session-create.ts
|
|
15
|
+
after-admin-user-create.ts
|
|
15
16
|
```
|
|
16
17
|
|
|
17
18
|
Each file has a single default export — an `async (entity, ctx) => ...` function. The filename determines which Better Auth event the hook fires on.
|
|
@@ -23,6 +24,9 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
|
|
|
23
24
|
| `before-user-create.ts` | `databaseHooks.user.create.before` | `User` | `void \| { data?: Partial<User> }` |
|
|
24
25
|
| `after-user-create.ts` | `databaseHooks.user.create.after` | `User` | `void` |
|
|
25
26
|
| `after-session-create.ts` | `databaseHooks.session.create.after` | `Session` | `void` |
|
|
27
|
+
| `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
|
|
28
|
+
|
|
29
|
+
`after-admin-user-create.ts` is a **virtual event** — it wires into the same Better Auth `user.create.after` slot as the generic `after-user-create.ts`, but the compiler wraps the call in a runtime filter on the BA context path so it only fires when the row was created via the admin plugin's `POST /admin/create-user` endpoint. Use it for first-time-user provisioning (welcome email, default org assignment) without inspecting `_baCtx?.context?.path` by hand. The generic `after-user-create.ts` still runs for every signup, including admin-created ones.
|
|
26
30
|
|
|
27
31
|
Filenames outside this set are a hard compile-time error so a typo never silently disables a hook. Add events by extending [`apps/compiler/src/parser/hooks.ts`](https://github.com/paulstenhouse/quickback-compiler) (and the matching CLI mirror).
|
|
28
32
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Quickback Account UI
|
|
2
2
|
|
|
3
|
-
A complete authentication and account management frontend. It handles login, signup, password reset, profile management, device sessions, passkeys, organizations, and admin — so you don't have to build any of it.
|
|
3
|
+
A complete authentication and account management frontend that ships with the Quickback Stack. It handles login, signup, password reset, profile management, device sessions, passkeys, organizations, and admin — so you don't have to build any of it.
|
|
4
4
|
|
|
5
5
|
## What's Included
|
|
6
6
|
|
|
@@ -20,9 +20,9 @@ Dashboard with org switching, org creation, member invitations, role management,
|
|
|
20
20
|
|
|
21
21
|
User management dashboard — view all users, search, create accounts, ban/unban, reset passwords, and manage sessions. Only accessible to users with the `admin` role. Can be served on its own domain (e.g., `admin.example.com`) via the `adminDomain` config.
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## How to Enable
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Add `account` to your `quickback.config.ts` and compile. The compiler builds the SPA from source with your project-specific settings baked in and bundles it into your Worker.
|
|
26
26
|
|
|
27
27
|
```typescript title="quickback/quickback.config.ts"
|
|
28
28
|
export default {
|
|
@@ -53,7 +53,7 @@ That's it. The compiler:
|
|
|
53
53
|
2. Generates a `.env` file with the correct `VITE_*` variables
|
|
54
54
|
3. Builds the SPA from source with Vite (inside Docker)
|
|
55
55
|
4. Excludes routes for disabled features (compile-time tree shaking)
|
|
56
|
-
5.
|
|
56
|
+
5. Bundles the built assets into your Worker alongside the API
|
|
57
57
|
|
|
58
58
|
No manual `.env` configuration needed. No separate deployment.
|
|
59
59
|
|
|
@@ -91,42 +91,6 @@ Auth feature flags control which pages are included in the bundle:
|
|
|
91
91
|
|
|
92
92
|
When a flag is `false`, the corresponding route files are **removed before the Vite build** — they never appear in the JavaScript bundle. This keeps production bundles minimal.
|
|
93
93
|
|
|
94
|
-
## Standalone Usage
|
|
95
|
-
|
|
96
|
-
Account UI also works outside of Quickback:
|
|
97
|
-
|
|
98
|
-
### Template (own the source)
|
|
99
|
-
|
|
100
|
-
Clone the repo and customize directly:
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
|
|
104
|
-
cd my-account-app
|
|
105
|
-
npm install
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Configure via `.env` files and deploy as a standalone Cloudflare Worker. See [Standalone Usage](/stack/account-ui/standalone) for Better Auth backends or [With Quickback](/stack/account-ui/with-quickback) for Quickback-compiled backends.
|
|
109
|
-
|
|
110
|
-
### Library (npm package)
|
|
111
|
-
|
|
112
|
-
Install as a dependency:
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
npm install quickback-better-auth-account-ui
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
```tsx
|
|
119
|
-
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
|
|
120
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
121
|
-
|
|
122
|
-
setAppConfig({
|
|
123
|
-
authRoute: 'quickback',
|
|
124
|
-
name: 'My App',
|
|
125
|
-
});
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
See [Library Usage](/stack/account-ui/library-usage) for details.
|
|
129
|
-
|
|
130
94
|
## Features
|
|
131
95
|
|
|
132
96
|
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, magic links, email verification, password reset
|
|
@@ -138,9 +102,7 @@ See [Library Usage](/stack/account-ui/library-usage) for details.
|
|
|
138
102
|
|
|
139
103
|
## Next Steps
|
|
140
104
|
|
|
141
|
-
- **[With Quickback](/stack/account-ui/with-quickback)** —
|
|
142
|
-
- **[Standalone Usage](/stack/account-ui/standalone)** — Use with any Better Auth backend
|
|
143
|
-
- **[Library Usage](/stack/account-ui/library-usage)** — Import as an npm package
|
|
105
|
+
- **[With Quickback](/stack/account-ui/with-quickback)** — Configuration reference for the `account` block
|
|
144
106
|
- **[Feature Flags](/stack/account-ui/features)** — Enable and disable features
|
|
145
107
|
- **[Environment Variables](/stack/account-ui/environment-variables)** — Configuration reference
|
|
146
108
|
- **[Customization](/stack/account-ui/customization)** — Branding, labels, and theming
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# With Quickback
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Account UI is part of the Quickback Stack. The compiler builds it from source and bundles it into your Worker — there is no separate npm package or standalone deploy path.
|
|
4
4
|
|
|
5
|
-
## Compiler-Embedded
|
|
5
|
+
## Compiler-Embedded
|
|
6
6
|
|
|
7
7
|
Add `account` to your `quickback.config.ts`:
|
|
8
8
|
|
|
@@ -77,79 +77,6 @@ auth: {
|
|
|
77
77
|
|
|
78
78
|
Disabled features are excluded at compile time — their route files are removed before the Vite build. See [Configuration](/compiler/config) for all options.
|
|
79
79
|
|
|
80
|
-
## Manual Deployment
|
|
81
|
-
|
|
82
|
-
If you need Account UI as a separate Worker (not embedded in the API Worker), you can deploy it standalone.
|
|
83
|
-
|
|
84
|
-
### 1. Clone the Template
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
|
|
88
|
-
cd my-account-app
|
|
89
|
-
npm install
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### 2. Configure for Quickback
|
|
93
|
-
|
|
94
|
-
Set the auth route mode to `quickback` to match Quickback's API paths:
|
|
95
|
-
|
|
96
|
-
```bash title=".env"
|
|
97
|
-
VITE_AUTH_ROUTE=quickback
|
|
98
|
-
# One variable points at the Quickback origin — API, Account, and CMS are all derived from it.
|
|
99
|
-
VITE_QUICKBACK_URL=https://secure.example.com
|
|
100
|
-
VITE_ACCOUNT_APP_URL=https://account.example.com
|
|
101
|
-
VITE_QUICKBACK_APP_URL=https://app.example.com
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
In Quickback mode, Account UI routes requests to three API paths:
|
|
105
|
-
|
|
106
|
-
| Path | Purpose | Examples |
|
|
107
|
-
|------|---------|---------|
|
|
108
|
-
| `/auth/v1/*` | Authentication | Login, signup, sessions, passkeys |
|
|
109
|
-
| `/api/v1/*` | Data API | Organizations, API keys |
|
|
110
|
-
| `/storage/v1/*` | File storage | Avatar uploads, file management |
|
|
111
|
-
|
|
112
|
-
### 3. Configure Features
|
|
113
|
-
|
|
114
|
-
Match your `quickback.config.ts` plugins:
|
|
115
|
-
|
|
116
|
-
```bash title=".env"
|
|
117
|
-
VITE_APP_NAME=My App
|
|
118
|
-
VITE_APP_TAGLINE=Build faster, ship sooner
|
|
119
|
-
ENABLE_SIGNUP=true
|
|
120
|
-
ENABLE_ORGANIZATIONS=true
|
|
121
|
-
ENABLE_PASSKEY=true
|
|
122
|
-
ENABLE_ADMIN=true
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### 4. Build and Deploy
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
npm run build
|
|
129
|
-
npx wrangler deploy
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
## Library Mode
|
|
133
|
-
|
|
134
|
-
Install as a dependency instead of cloning:
|
|
135
|
-
|
|
136
|
-
```bash
|
|
137
|
-
npm install quickback-better-auth-account-ui
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
```tsx
|
|
141
|
-
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
|
|
142
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
143
|
-
|
|
144
|
-
setAppConfig({
|
|
145
|
-
authRoute: 'quickback',
|
|
146
|
-
name: 'My App',
|
|
147
|
-
companyName: 'My Company',
|
|
148
|
-
});
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
See [Library Usage](/stack/account-ui/library-usage) for the complete guide.
|
|
152
|
-
|
|
153
80
|
## Next Steps
|
|
154
81
|
|
|
155
82
|
- [Configuration](/compiler/config) — CMS and Account config reference
|
|
@@ -44,6 +44,66 @@ Each email type has both HTML and plain text templates. Templates include:
|
|
|
44
44
|
- Fallback plain text versions for all email clients
|
|
45
45
|
- XSS prevention via HTML escaping and URL sanitization
|
|
46
46
|
|
|
47
|
+
### Per-Type Template Overrides
|
|
48
|
+
|
|
49
|
+
Override the default subject + HTML + text for any OTP type without forking the package. Drop a `.ts` file into `quickback/email-templates/` and reference it from `plugins.emailOtp.templates`:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// quickback/quickback.config.ts
|
|
53
|
+
defineAuth("better-auth", {
|
|
54
|
+
plugins: {
|
|
55
|
+
emailOtp: {
|
|
56
|
+
templates: {
|
|
57
|
+
'forget-password': './email-templates/forget-password',
|
|
58
|
+
'welcome': './email-templates/welcome',
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Each template module default-exports a function that returns `{ subject, html, text }`:
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
// quickback/email-templates/welcome.ts
|
|
69
|
+
interface Input {
|
|
70
|
+
email: string;
|
|
71
|
+
otp: string;
|
|
72
|
+
type: 'sign-in' | 'email-verification' | 'forget-password' | 'welcome';
|
|
73
|
+
name?: string;
|
|
74
|
+
appName: string;
|
|
75
|
+
appUrl: string;
|
|
76
|
+
supportEmail?: string;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
|
|
80
|
+
const greeting = name ? `Hi ${name},` : 'Hi,';
|
|
81
|
+
return {
|
|
82
|
+
subject: `Welcome to ${appName} — set your password`,
|
|
83
|
+
html: `
|
|
84
|
+
<h1>Welcome to ${appName}</h1>
|
|
85
|
+
<p>${greeting} your account is ready. Use this code to set your password and sign in:</p>
|
|
86
|
+
<p style="font-size:32px;letter-spacing:8px"><b>${otp}</b></p>
|
|
87
|
+
<p>Visit <a href="${appUrl}/set-password">${appUrl}/set-password</a> to finish setup.</p>
|
|
88
|
+
`,
|
|
89
|
+
text: `${greeting}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Recognized keys:
|
|
95
|
+
|
|
96
|
+
| Key | When it fires |
|
|
97
|
+
|-----|---------------|
|
|
98
|
+
| `'sign-in'` | OTP sign-in flow |
|
|
99
|
+
| `'email-verification'` | Signup email verification |
|
|
100
|
+
| `'forget-password'` | Password reset request — and admin-bootstrap if `welcome` isn't set |
|
|
101
|
+
| `'welcome'` | **Synthetic** — routed when `forget-password` fires for a user with no credential row yet (the admin-plugin → bootstrap flow). Without it, those sends fall through to `forget-password`. |
|
|
102
|
+
|
|
103
|
+
Missing keys fall through to the built-in defaults from `@quickback-dev/better-auth-aws-ses`. The compiler stages each referenced file into `src/email-templates/<name>.ts` and wires the default import in `src/lib/auth.ts` — the template function is called inline from `sendVerificationOTP`, so it has access to whatever modules the file imports.
|
|
104
|
+
|
|
105
|
+
> **Provider scope.** Overrides are only honored when `email.provider: 'aws-ses'`. The Cloudflare Email path uses the helper's own template pipeline and ignores `plugins.emailOtp.templates`.
|
|
106
|
+
|
|
47
107
|
## Configuration
|
|
48
108
|
|
|
49
109
|
### Server Plugin
|