@quickback-dev/cli 0.17.1 → 0.18.0

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.
@@ -331,6 +331,80 @@ Better Auth's older `better-auth/plugins/mcp` is being deprecated in favour of `
331
331
 
332
332
  Keep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.
333
333
 
334
+ ### Custom plugins (escape hatch)
335
+
336
+ The named plugins above cover the curated set Quickback ships first-class wiring for. For anything else — third-party packages (`@better-auth-kit/audit`, …), Better Auth built-ins outside the registry, or project-local plugins — use `customPlugins`.
337
+
338
+ ```ts
339
+ auth: defineAuth("better-auth", {
340
+ emailAndPassword: { enabled: true },
341
+ plugins: { passkey: true, organization: true },
342
+ customPlugins: [
343
+ // (1) Project-local plugin file at quickback/plugins/long-session.ts
344
+ { from: "./plugins/long-session", export: "longSessionPlugin" },
345
+ // (2) Third-party npm package
346
+ {
347
+ from: "@better-auth-kit/audit",
348
+ export: "auditPlugin",
349
+ args: { events: ["sign-in"] },
350
+ dependencies: { "@better-auth-kit/audit": "^1.0.0" },
351
+ },
352
+ ],
353
+ }),
354
+ ```
355
+
356
+ Each entry in `customPlugins` is an explicit import descriptor. The compiler runs each through Zod, then emits an `import { <export> } from "<from>"` line in the generated `src/lib/auth.ts` and appends the call (or bare symbol) to the `plugins: [...]` array — after the named plugins, in declared order.
357
+
358
+ #### `from`
359
+
360
+ - **Relative path** (must start with `./` or `../`, must resolve under `./plugins/`): refers to a file you author in `quickback/plugins/`. The CLI auto-discovers `quickback/plugins/**/*.ts` and ships matching files; the compiler copies the source into the generated output at `src/plugins/<name>.ts` and rewrites the emitted import path. Files in `quickback/plugins/` that aren't referenced by any descriptor are uploaded but ignored — the compiler picks only what's needed.
361
+ - **Bare specifier** (any value not starting with `./` or `../`): treated as an npm import, emitted verbatim. Combine with `dependencies` so the package lands in the generated `package.json`.
362
+
363
+ #### `export`
364
+
365
+ The named export to import. Must be a valid JS identifier (e.g. `longSessionPlugin`, `auditPlugin`). Use the symbol's source name from the file or package — Quickback emits the import as-is.
366
+
367
+ #### `args` (optional)
368
+
369
+ - **Omitted** → emits the symbol uncalled (`plugins: [..., longSessionPlugin]`). Use this when your export is already a `BetterAuthPlugin` instance.
370
+ - **Provided** → emits a factory call with JSON-serialized args (`plugins: [..., auditPlugin({"events":["sign-in"]})]`). The value must be JSON-serializable; functions and other non-serializable values fail at compile time. (The user config crosses an HTTP boundary as JSON, so this constraint exists by construction.)
371
+
372
+ #### `dependencies` (optional)
373
+
374
+ `Record<string, string>` of npm packages and version specs. Merged into the generated `package.json` alongside the named-plugin deps. Only meaningful for bare-specifier `from` — relative-path entries don't need to declare anything.
375
+
376
+ #### Project-local plugin shape
377
+
378
+ A plugin file in `quickback/plugins/` is plain Better Auth — the compiler doesn't transform it. Author it like any other BA plugin and let TypeScript check it against the `BetterAuthPlugin` type:
379
+
380
+ ```ts
381
+ // quickback/plugins/long-session.ts
382
+ import type { BetterAuthPlugin } from "better-auth";
383
+
384
+ export const longSessionPlugin = {
385
+ id: "long-session",
386
+ databaseHooks: {
387
+ session: {
388
+ create: {
389
+ before: async (session) => ({
390
+ data: {
391
+ ...session,
392
+ // 5-year session for an event-app use case
393
+ expiresAt: new Date(Date.now() + 5 * 365 * 24 * 60 * 60 * 1000),
394
+ },
395
+ }),
396
+ },
397
+ },
398
+ },
399
+ } satisfies BetterAuthPlugin;
400
+ ```
401
+
402
+ #### Out of scope
403
+
404
+ - **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature — the compiler does not run schema introspection on custom plugins.
405
+ - **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.
406
+ - **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.
407
+
334
408
  ## Where This Runs
335
409
 
336
410
  All Better Auth plugin routes are served under your auth base path:
@@ -51,13 +51,17 @@ Quickback provides the architecture and the code generation. You own the infrast
51
51
  ## Quick start
52
52
 
53
53
  ```bash
54
- npm install -g wrangler @quickback-dev/cli
55
- quickback create cloudflare my-app
56
- cd my-app
57
- quickback compile
54
+ # Scaffold + compile interactively
55
+ mkdir my-app && cd my-app
56
+ npx @quickback-dev/cli start
57
+
58
+ # Deploy to your Cloudflare account
59
+ npm i -g wrangler
58
60
  wrangler deploy
59
61
  ```
60
62
 
63
+ `start` handles scaffold, login (only when needed), and the first compile in one shot. The deploy step uses your own wrangler auth and ships everything to your Cloudflare account.
64
+
61
65
  ## See also
62
66
 
63
67
  - [Quickback Compiler](/compiler) — the build tool that generates your API