create-basalt 1.7.0 → 1.9.0

package/README.md

@@ -48,6 +48,7 @@ Subscriptions / billing? (y/N) n
 Web UI (React + shadcn)? (y/N) n
 MCP server (routes as AI-agent tools)? (y/N) n
 'basalt' CLI (code generators)? (y/N) n
+Database (PostgreSQL via Prisma)? (y/N) n
 Install dependencies now? (y/N) y
 Initialize a git repository? (y/N) y
 ```
@@ -91,6 +92,7 @@ Usage: npm create basalt <name> [options]
 | `--ui` | off | Generates the `web/` frontend (React + shadcn via `@basaltkit/admin-shadcn` + `@basaltkit/sdk`). **Forces pnpm** — see note below |
 | `--cli` | off | Generates the `basalt` CLI (`bin/basalt.ts`, `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
 | `--mcp` | off | Exposes read-only routes as MCP tools (`@basaltkit/mcp`) over HTTP at `POST /mcp` — the overview and health endpoints are opted in via `meta.mcp` |
+| `--prisma` (alias `--db`) | off | Backs the app with PostgreSQL through Prisma: `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, the `@basaltkit/*-prisma` stores instead of the in-memory ones, a required `<APP>_DATABASE_URL`, the `db:*` scripts and `prismaPlugin({ assertMigrated: true })` — see *With `--prisma`* below |
 | `--install` | off | Installs dependencies at the end (with the detected/chosen manager) |
 | `--git` | off | Runs `git init` + first commit ("Initial commit from create-basalt") |
 | `--offline` | off | Don't query the npm registry for the latest versions; use the ranges bundled with this create-basalt release |
@@ -115,7 +117,7 @@ Behavior notes (faithful to the code):
 pnpm create basalt
 
 # Full project, no questions, with everything:
-pnpm create basalt my-app --billing --ui --cli --install --git
+pnpm create basalt my-app --billing --ui --cli --prisma --install --git
 
 # Minimal API (no tenancy or auth), in another folder:
 npm create basalt service-api --no-tenancy --no-auth --dir=./apps/service-api
@@ -147,7 +149,7 @@ my-app/
 └── tests/app.test.ts     # smoke test adapted to the options
 ```
 
-With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
+With `--prisma`, adds `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, `prisma/seed.ts` (with tenancy) and the `db:generate` / `db:migrate` / `db:deploy` / `db:seed` scripts. With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
 
 ### With `--ui`: running the API and frontend
 
@@ -159,6 +161,44 @@ pnpm --filter my-app-web dev       # terminal 2 — UI at http://localhost:5180
 
 Vite's dev server proxies `/api` to the API — there's no CORS to configure.
 
+### With `--prisma`: a PostgreSQL-backed app
+
+Without the flag the generated app has **no database**: it boots on
+`MemoryUserSource` / `MemoryTenantSource` and the default in-memory team and
+subscription stores, which is ideal for a first run and for CI and is gone on
+the next restart.
+
+`--prisma` (or `--db`) generates the database-backed shape instead:
+
+| File | What it holds |
+| --- | --- |
+| `prisma/schema.prisma` | The reference models of every `@basaltkit/*-prisma` package the project uses — the same blocks `basalt prisma:sync` merges — plus a `Project` model of your own |
+| `prisma.config.ts` | Prisma 7 keeps the connection URL here. It reads `MY_APP_DATABASE_URL` first and the bare `DATABASE_URL` only as a fallback — the same precedence as `src/env.ts`, so the CLI and the app can never mean two different databases |
+| `src/db.ts` | `prisma` (unscoped — the framework stores use it, they run before a tenant is known) and, with tenancy, `db = prisma.$extends(tenancyExtension())` |
+| `src/app.ts` | `prismaPlugin({ client: db, assertMigrated: true })`, `prismaTenantSource`, `prismaAuthStores`, `prismaTeamsStores`, `prismaSubscriptionsStores` |
+| `prisma/seed.ts` | The `demo` tenant the header and subdomain resolvers expect |
+
+```bash
+pnpm create basalt my-app --prisma
+cd my-app && pnpm install     # postinstall runs `prisma generate`
+cp .env.example .env          # point MY_APP_DATABASE_URL at your database
+pnpm db:migrate               # prisma migrate dev — creates the tables and seeds `demo`
+pnpm dev
+```
+
+**Migrations, never `prisma db push`.** The generated app boots with
+`assertMigrated: true`, which refuses to start unless the database it reached has
+the `_prisma_migrations` table — written by `prisma migrate dev` /
+`prisma migrate deploy`, and *not* by `db push`. That is what turns a wrong
+`DATABASE_URL` (a shell that exported another project's) into a boot error naming
+the database and host instead of a `500` on the first request. In production:
+`pnpm db:deploy`.
+
+The generated `tests/app.test.ts` skips itself when no database is configured, so
+`pnpm test` stays green on a machine without PostgreSQL. To add another Basalt
+domain later, install its `@basaltkit/<domain>-prisma` package, run
+`pnpm basalt prisma:sync` (with `--cli`) and then `pnpm db:migrate`.
+
 ### With `--cli`: the `basalt` command line
 
 ```bash
@@ -240,6 +280,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | `ui` | `boolean` | No | `false` | Generate the `web/` frontend |
 | `cli` | `boolean` | No | `false` | Generate the `basalt` CLI |
 | `mcp` | `boolean` | No | `false` | Expose read-only routes as MCP tools at `/mcp` |
+| `prisma` | `boolean` | No | `false` | Back the app with PostgreSQL through Prisma (schema, migrations, Prisma-backed stores, `assertMigrated`) |
 | `resolveLatest` | `boolean` | No | `false` | Resolve every dependency to `^<latest>` from the npm registry before writing (falls back to the bundled ranges on any registry failure) |
 | `registry` | `ResolveLatestOptions` | No | — | `{ fetch?, registry?, timeoutMs?, overallTimeoutMs?, concurrency?, minimumReleaseAge?, now? }` — injectable fetch (tests), registry URL (default `npm_config_registry` or `https://registry.npmjs.org`), timeouts (5 s per request, 15 s overall), release-age window in minutes (default `pnpm_config_minimum_release_age` / `npm_config_minimum_release_age`, else 1440; `0` disables the probe), clock (tests) |
 
@@ -267,7 +308,7 @@ Error (extends `Error`) with the message `Target directory "<dir>" already exist
 | Type | Description |
 | --- | --- |
 | `PackageManager` | `'pnpm' \| 'npm' \| 'yarn' \| 'bun'` |
-| `ProjectOptions` | `{ name, tenancy, auth, billing, ui, cli }` — all resolved (no optionals) |
+| `ProjectOptions` | `{ name, tenancy, auth, billing, ui, cli, mcp, prisma }` — all resolved (no optionals) |
 | `CreateProjectInput`, `CreateProjectResult` | Described above |
 
 ## Common errors and solutions (FAQ)
@@ -290,6 +331,20 @@ Automatic installation failed (network, Node version, etc.). Go into the folder
 **I started the app and `GET /auth/login` gives a secret error.**
 With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). Copy `.env.example` to `.env` and set your own secret before going to production.
 
+**With `--prisma`, the app refuses to boot: `PRISMA_NOT_MIGRATED`.**
+`assertMigrated` reached a database without the `_prisma_migrations` table. The
+message names the database and host it actually reached (never the
+credentials): either it is not the database you meant — check
+`env | grep DATABASE_URL`, a shell may have exported another project's — or it
+was never migrated: run `pnpm db:migrate` (development) or `pnpm db:deploy`
+(production). A database set up with `prisma db push` has no
+`_prisma_migrations` at all; this scaffold is migration-based on purpose.
+
+**With `--prisma`, `pnpm typecheck` can't find `./generated/prisma/client.js`.**
+The Prisma client is generated code, not a checked-in file. `pnpm install` runs
+`prisma generate` for you (`postinstall`); after a `git clone` without install,
+or after editing the schema, run `pnpm db:generate`.
+
 **My app connects to the wrong database / port.**
 A variable exported in your shell beats `--env-file`. The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
 
@@ -307,6 +362,7 @@ There's no "re-scaffold" command. Either generate a new project with the right f
 - **`@basaltkit/tenancy`** — included by default (remove with `--no-tenancy`): header and subdomain resolvers, with a demo `MemoryTenantSource`.
 - **`@basaltkit/auth`** — included by default (remove with `--no-auth`): `/auth/*` routes and `APP_SECRET` validated in `env.ts`.
 - **`@basaltkit/subscriptions`** — with `--billing`: example `free`/`pro` plans with trial and feature limits.
+- **`@basaltkit/prisma` + `@basaltkit/{tenancy,auth,teams,subscriptions}-prisma`** — with `--prisma`: the PostgreSQL layer — `prismaPlugin` (tenant-scoped client, boot-time `assertMigrated`), the composed `prisma/schema.prisma` and the Prisma-backed stores for whichever domains are on.
 - **`@basaltkit/cli` + `@basaltkit/generator`** — with `--cli`: `bin/basalt.ts` calls `runCli`, and `commandsPlugin(generatorCommands())` registers the `make:*` generators.
 - **`@basaltkit/sdk` + `@basaltkit/admin-shadcn` + `@basaltkit/admin`** — with `--ui`: the `web/` frontend calls the API through a typed client and uses the shadcn components.
 - **`@basaltkit/testing`** — always present in `devDependencies`, with a generated smoke test in `tests/app.test.ts`.

package/dist/args.d.ts

@@ -1,5 +1,5 @@
 import type { PackageManager } from './index.js';
-export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --cli           Scaffold the 'basalt' CLI (code generators + commands)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n";
+export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --cli           Scaffold the 'basalt' CLI (code generators + commands)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,\n                  migrations, prisma-backed stores and a boot-time check\n                  that the database is the migrated one\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n";
 export interface Flags {
     name?: string;
     dir?: string;
@@ -9,6 +9,7 @@ export interface Flags {
     ui: boolean;
     cli: boolean;
     mcp: boolean;
+    prisma: boolean;
     /** Tri-state: undefined = decide from the environment (TTY yes, CI no). */
     install?: boolean;
     git?: boolean;

package/dist/args.js

@@ -9,6 +9,9 @@ Options:
   --ui            Scaffold a web/ frontend (React + shadcn + SDK)
   --cli           Scaffold the 'basalt' CLI (code generators + commands)
   --mcp           Expose read-only routes as MCP tools at /mcp
+  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,
+                  migrations, prisma-backed stores and a boot-time check
+                  that the database is the migrated one
   --install       Install dependencies (default: yes in an interactive
                   terminal, skipped in CI/non-TTY; --no-install to opt out)
   --no-install    Never install dependencies
@@ -31,6 +34,7 @@ export function parseArgs(argv) {
         ui: false,
         cli: false,
         mcp: false,
+        prisma: false,
         yes: false,
         offline: false,
     };
@@ -47,6 +51,10 @@ export function parseArgs(argv) {
             flags.cli = true;
         else if (token === '--mcp')
             flags.mcp = true;
+        // `--db` reads naturally in a sentence ("scaffold it with a db") and is the
+        // same switch; the canonical spelling stays the package name, like --mcp.
+        else if (token === '--prisma' || token === '--db')
+            flags.prisma = true;
         else if (token === '--install')
             flags.install = true;
         else if (token === '--no-install')

package/dist/cli.js

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
 import { stdin, stdout } from 'node:process';
 import { createProject, describeResolution, detectPackageManager, resolveRunDefaults, runWizard, ttyPrompter, TargetNotEmptyError, WizardCancelledError, } from './index.js';
 import { parseArgs, resolvesLatest, USAGE } from './args.js';
+import { envPrefix } from './templates.js';
 /** Runs a command inheriting stdio; resolves false on non-zero exit (never throws). */
 function run(command, args, cwd) {
     return new Promise((resolve) => {
@@ -35,6 +36,7 @@ if (!flags.yes && flags.name === undefined && stdin.isTTY) {
         flags.ui = result.ui;
         flags.cli = result.cli;
         flags.mcp = result.mcp;
+        flags.prisma = result.prisma;
         flags.install = result.install;
         flags.git = result.git;
         flags.pm = result.pm;
@@ -68,6 +70,7 @@ try {
         ui: flags.ui,
         cli: flags.cli,
         mcp: flags.mcp,
+        prisma: flags.prisma,
         // New apps get the latest published version of every dependency (with the
         // bundled ranges as an offline fallback); --offline skips the registry.
         resolveLatest: resolvesLatest(flags),
@@ -108,6 +111,12 @@ try {
     const steps = [`cd ${result.dir}`];
     if (!run_.install)
         steps.push(`${pm} install`);
+    if (flags.prisma) {
+        // Nothing boots before the database exists: env.DATABASE_URL is required and
+        // the app asserts at boot that it reached the MIGRATED database.
+        steps.push(`cp .env.example .env   # then point ${envPrefix(result.options.name)}_DATABASE_URL at your database`);
+        steps.push(`${pm} run db:migrate${flags.tenancy ? '   # creates the tables and seeds the demo tenant' : '   # creates the tables'}`);
+    }
     steps.push(`${pm} run dev${flags.ui ? '        # API on :3000' : ''}`);
     // `web` is wired as a pnpm workspace member (pnpm-workspace.yaml), so its dev
     // server is launched with a pnpm filter regardless of the root package manager.

package/dist/index.d.ts

@@ -14,6 +14,12 @@ export interface CreateProjectInput {
     cli?: boolean;
     /** Expose opted-in routes as MCP tools over HTTP at `/mcp`. Default: false. */
     mcp?: boolean;
+    /**
+     * Back the app with PostgreSQL through Prisma: `prisma/schema.prisma`,
+     * `src/db.ts`, `prismaPlugin({ assertMigrated: true })` and the Prisma-backed
+     * stores instead of the in-memory ones. Default: false (no database at all).
+     */
+    prisma?: boolean;
     /**
      * Resolve every dependency to its latest published version (npm registry)
      * before writing files. Default: false — the embedded fallback ranges are

package/dist/index.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { appTest, appTs, dbTs, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
 import { uiFiles } from './templates-ui.js';
 import { applyVersions, collectDependencies, resolveLatestVersions, } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
@@ -45,6 +45,7 @@ export async function createProject(input) {
         ui: input.ui ?? false,
         cli: input.cli ?? false,
         mcp: input.mcp ?? false,
+        prisma: input.prisma ?? false,
     };
     const dir = resolve(input.dir ?? input.name);
     const existing = await readdir(dir).catch(() => null);
@@ -52,9 +53,9 @@ export async function createProject(input) {
         throw new TargetNotEmptyError(dir);
     const files = {
         'package.json': packageJson(options),
-        'tsconfig.json': tsconfigJson(),
+        'tsconfig.json': tsconfigJson(options),
         '.env.example': envExample(options),
-        '.gitignore': gitignore(),
+        '.gitignore': gitignore(options),
         '.dockerignore': dockerignore(),
         'README.md': readme(options),
         'pnpm-workspace.yaml': pnpmWorkspaceYaml(options),
@@ -64,6 +65,15 @@ export async function createProject(input) {
         'src/server.ts': serverTs(),
         'src/dev.ts': devTs(),
         'tests/app.test.ts': appTest(options),
+        ...(options.prisma
+            ? {
+                'prisma/schema.prisma': prismaSchema(options),
+                'prisma.config.ts': prismaConfigTs(options),
+                'src/db.ts': dbTs(options),
+                // The demo tenant only exists where tenancy does.
+                ...(options.tenancy ? { 'prisma/seed.ts': prismaSeedTs(options) } : {}),
+            }
+            : {}),
         ...(options.cli ? { 'bin/basalt.ts': basaltBin() } : {}),
         ...(options.mcp ? { '.mcp.json': mcpJson(options) } : {}),
         ...(options.ui ? uiFiles(options) : {}),

package/dist/latest-versions.js

@@ -31,12 +31,17 @@
  * major. Bump a range to a new major only together with the templates.
  */
 export const THIRD_PARTY_VERSIONS = {
+    '@prisma/adapter-pg': '^7.10.0',
+    '@prisma/client': '^7.10.0',
     '@tailwindcss/vite': '^4.3.3',
     '@types/node': '^26.6.2',
+    '@types/pg': '^8.15.6',
     '@types/react': '^19.3.0',
     '@types/react-dom': '^19.3.0',
     '@vitejs/plugin-react': '^6.1.1',
+    pg: '^8.16.3',
     'pino-pretty': '^13.1.3',
+    prisma: '^7.10.0',
     react: '^19.3.0',
     'react-dom': '^19.3.0',
     tailwindcss: '^4.3.3',

package/dist/templates.d.ts

@@ -9,6 +9,12 @@ export interface ProjectOptions {
     cli: boolean;
     /** Expose opted-in routes as MCP tools (@basaltkit/mcp) over HTTP at `/mcp`. */
     mcp: boolean;
+    /**
+     * Back the app with a real PostgreSQL database: a `prisma/schema.prisma`,
+     * `src/db.ts`, `prismaPlugin({ assertMigrated: true })` and the Prisma-backed
+     * stores instead of the in-memory ones.
+     */
+    prisma: boolean;
 }
 export { SCAFFOLD_VERSIONS } from './versions.js';
 export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
@@ -29,7 +35,7 @@ export declare const thirdPartyVersionOf: (pkg: string) => string;
 /** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
 export declare const enforcesMembership: (options: ProjectOptions) => boolean;
 export declare function packageJson(options: ProjectOptions): string;
-export declare function tsconfigJson(): string;
+export declare function tsconfigJson(options: ProjectOptions): string;
 export declare function envTs(options: ProjectOptions): string;
 /**
  * An app-specific env-var prefix derived from the project name
@@ -38,6 +44,8 @@ export declare function envTs(options: ProjectOptions): string;
  */
 export declare function envPrefix(name: string): string;
 export declare function envExample(options: ProjectOptions): string;
+/** A PostgreSQL-safe database name derived from the project name. */
+export declare function databaseName(name: string): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
 export declare function serverTs(): string;
@@ -49,6 +57,34 @@ export declare function serverTs(): string;
  */
 export declare function devTs(): string;
 export declare function basaltBin(): string;
+/**
+ * `prisma/schema.prisma` — the datasource, the client generator, the models of
+ * every Basalt domain this app enables, and the app's own first model.
+ *
+ * Prisma 7 no longer takes the connection URL here (prisma.config.ts does), and
+ * the client needs an explicit `output`; src/db.ts imports it from there.
+ */
+export declare function prismaSchema(options: ProjectOptions): string;
+/**
+ * `prisma.config.ts` — Prisma 7 reads the connection URL (and the seed command)
+ * from here instead of from schema.prisma. It applies the SAME precedence as
+ * src/env.ts: the app-prefixed name first, the bare `DATABASE_URL` only as a
+ * fallback, so the CLI and the running app can never mean different databases.
+ */
+export declare function prismaConfigTs(options: ProjectOptions): string;
+/**
+ * `src/db.ts` — the Prisma client(s). Two bindings on purpose: the unscoped
+ * `prisma` for the framework stores (they key their own rows and run outside a
+ * tenant context) and, with tenancy, the `db` client the whole application uses,
+ * where every query is filtered by the request's tenant.
+ */
+export declare function dbTs(options: ProjectOptions): string;
+/**
+ * `prisma/seed.ts` — creates the `demo` tenant the scaffolded resolvers expect
+ * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed` and after
+ * `prisma migrate dev` (prisma.config.ts declares it).
+ */
+export declare function prismaSeedTs(options: ProjectOptions): string;
 export declare function appTest(options: ProjectOptions): string;
 export declare function readme(options: ProjectOptions): string;
 /**
@@ -65,7 +101,7 @@ export declare function mcpJson(_options: ProjectOptions): string;
  * `certs/server.key` through.
  */
 export declare function dockerignore(): string;
-export declare function gitignore(): string;
+export declare function gitignore(options: ProjectOptions): string;
 /**
  * pnpm settings: esbuild's build script is required by tsx;
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —

package/dist/templates.js

@@ -46,13 +46,34 @@ export function packageJson(options) {
         basalt.push('@basaltkit/mcp');
     if (options.cli) {
         // Runtime deps: app.ts uses commandsPlugin (@basaltkit/cli); prisma powers
-        // `basalt prisma:sync` (and prismaPlugin once the app adds a PrismaClient —
-        // the scaffold wires no database itself). @basaltkit/generator is dev-only (below).
+        // `basalt prisma:sync` (and prismaPlugin, wired by --prisma).
+        // @basaltkit/generator is dev-only (below).
         basalt.push('@basaltkit/cli', '@basaltkit/prisma');
     }
+    if (options.prisma) {
+        // The database layer: prismaPlugin + tenancyExtension, plus the store
+        // packages for whichever domains are on (the memory ones are gone).
+        if (!options.cli)
+            basalt.push('@basaltkit/prisma');
+        if (options.tenancy)
+            basalt.push('@basaltkit/tenancy-prisma');
+        if (options.auth)
+            basalt.push('@basaltkit/auth-prisma');
+        if (enforcesMembership(options))
+            basalt.push('@basaltkit/teams-prisma');
+        if (options.billing)
+            basalt.push('@basaltkit/subscriptions-prisma');
+    }
     const dependencies = { zod: thirdPartyVersionOf('zod') };
     for (const pkg of basalt)
         dependencies[pkg] = versionOf(pkg);
+    if (options.prisma) {
+        // Prisma 7 talks to PostgreSQL through a driver adapter, so `pg` is a real
+        // runtime dependency (see src/db.ts); the `prisma` CLI is dev-only.
+        for (const pkg of ['@prisma/adapter-pg', '@prisma/client', 'pg']) {
+            dependencies[pkg] = thirdPartyVersionOf(pkg);
+        }
+    }
     const devDependencies = {
         '@basaltkit/testing': versionOf('@basaltkit/testing'),
     };
@@ -70,6 +91,10 @@ export function packageJson(options) {
         // app ships and runs without it (see `.mcp.json` for the client config).
         devDependencies['@basaltkit/ai-mcp'] = versionOf('@basaltkit/ai-mcp');
     }
+    if (options.prisma) {
+        for (const pkg of ['@types/pg', 'prisma'])
+            devDependencies[pkg] = thirdPartyVersionOf(pkg);
+    }
     return `${JSON.stringify({
         name: options.name,
         version: '0.1.0',
@@ -83,12 +108,27 @@ export function packageJson(options) {
             test: 'vitest run',
             typecheck: 'tsc --noEmit',
             ...(options.cli ? { basalt: 'tsx bin/basalt.ts' } : {}),
+            ...(options.prisma
+                ? {
+                    // Generate right after install so `pnpm typecheck` has the client
+                    // types (generation needs no database).
+                    postinstall: 'prisma generate',
+                    'db:generate': 'prisma generate',
+                    // Development and deployment BOTH go through migrations: they are
+                    // what creates `_prisma_migrations`, which the app's
+                    // prismaPlugin({ assertMigrated: true }) requires at boot. There
+                    // is deliberately no `db:push` script.
+                    'db:migrate': 'prisma migrate dev',
+                    'db:deploy': 'prisma migrate deploy',
+                    ...(options.tenancy ? { 'db:seed': 'tsx prisma/seed.ts' } : {}),
+                }
+                : {}),
         },
         dependencies: Object.fromEntries(Object.entries(dependencies).sort()),
         devDependencies: Object.fromEntries(Object.entries(devDependencies).sort()),
     }, null, 2)}\n`;
 }
-export function tsconfigJson() {
+export function tsconfigJson(options) {
     return `${JSON.stringify({
         compilerOptions: {
             target: 'ES2022',
@@ -101,7 +141,10 @@ export function tsconfigJson() {
             noEmit: true,
             types: ['node'],
         },
-        include: ['src', 'tests'],
+        // The generated Prisma client lives under src/generated (git-ignored, and
+        // re-created by `prisma generate`); the seed script under prisma/ is
+        // type-checked too.
+        include: ['src', 'tests', ...(options.prisma && options.tenancy ? ['prisma/seed.ts'] : [])],
     }, null, 2)}\n`;
 }
 export function envTs(options) {
@@ -119,7 +162,14 @@ export const env = defineEnv(
     LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
     // Unset counts as production (fail-closed); \`pnpm dev\` sets development.
     // NODE_ENV is a Node-wide convention and is never prefixed.
-    NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.auth
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.prisma
+        ? `
+    // Required: the PostgreSQL connection string, read as ${prefix}_DATABASE_URL
+    // first (a stray DATABASE_URL exported in your shell must not win — that is
+    // how an app boots against another project's database). src/db.ts builds the
+    // Prisma client from it; prisma.config.ts gives the CLI the same URL.
+    DATABASE_URL: z.string().min(1),`
+        : ''}${options.auth
         ? `
     // Signs JWTs and sessions. secret() is fail-closed: required unless NODE_ENV
     // is explicitly development/test (no fallback when NODE_ENV is unset),
@@ -179,10 +229,20 @@ ${options.auth
 # without it. Generate a strong one:  openssl rand -base64 48
 # ${prefix}_APP_SECRET=
 `
-        : ''}# When you add a database, declare DATABASE_URL in src/env.ts and set it here
-# under the prefixed name:
+        : ''}${options.prisma
+        ? `# Required: the app does not boot without it. The Prisma CLI reads the same
+# name from prisma.config.ts, so \`pnpm db:migrate\` and the running app always
+# agree on which database they mean.
+${prefix}_DATABASE_URL=postgres://postgres:postgres@localhost:5432/${databaseName(options.name)}
+`
+        : `# When you add a database, declare DATABASE_URL in src/env.ts and set it here
+# under the prefixed name (or scaffold with --prisma, which does it for you):
 # ${prefix}_DATABASE_URL=postgres://user:pass@localhost:5432/${options.name.replace(/^@[^/]+\//, '')}
-`;
+`}`;
+}
+/** A PostgreSQL-safe database name derived from the project name. */
+export function databaseName(name) {
+    return name.replace(/^@[^/]+\//, '').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
 }
 export function appTs(options) {
     const imports = [
@@ -207,24 +267,73 @@ export function appTs(options) {
     })`,
     ];
     let routesExpression = 'appRoutes';
+    /** Module-level bindings emitted between the imports and `buildApp`. */
+    const preamble = [];
+    if (options.prisma) {
+        imports.push(`import { prismaPlugin } from '@basaltkit/prisma'`);
+        imports.push(`import { db, prisma } from './db.js'`);
+        plugins.push(`prismaPlugin({
+      // \`db\` is the tenant-scoped client (src/db.ts): db<PrismaClient>() in a
+      // handler returns it, already filtered by the request's tenant.
+      client: db,
+      // Fail the BOOT when this database is not the migrated one — a shell that
+      // exported another project's DATABASE_URL, a typo in the database name.
+      // Without it the app starts and dies on the first query instead. Needs
+      // \`prisma migrate dev\`/\`migrate deploy\` (they write _prisma_migrations);
+      // \`prisma db push\` does not, so never use it against this app.
+      assertMigrated: true,
+    })`);
+    }
     if (options.tenancy) {
-        imports.push(`import { headerResolver, MemoryTenantSource, subdomainResolver, tenancyPlugin } from '@basaltkit/tenancy'`);
-        plugins.push(`tenancyPlugin({
+        if (options.prisma) {
+            imports.push(`import { headerResolver, subdomainResolver, tenancyPlugin } from '@basaltkit/tenancy'`);
+            imports.push(`import { prismaTenantSource } from '@basaltkit/tenancy-prisma'`);
+            // The stores read their own tables, outside any tenant context (a login
+            // happens before a tenant is known) — so they take the UNSCOPED client.
+            preamble.push(`/** Tenants live in the \`tenants\` table — seed one with \`pnpm db:seed\`. */
+const tenants = prismaTenantSource(prisma)`);
+            plugins.push(`tenancyPlugin({
+      source: tenants,
+      resolvers: [headerResolver(), subdomainResolver({ base: 'localhost' })],
+    })`);
+        }
+        else {
+            imports.push(`import { headerResolver, MemoryTenantSource, subdomainResolver, tenancyPlugin } from '@basaltkit/tenancy'`);
+            plugins.push(`tenancyPlugin({
       // Replace MemoryTenantSource with your database-backed source.
       source: new MemoryTenantSource().add({ id: 'demo', name: 'Demo Tenant' }),
       resolvers: [headerResolver(), subdomainResolver({ base: 'localhost' })],
     })`);
+        }
     }
     if (options.auth) {
-        imports.push(`import { authPlugin, authRoutes, mfaRoutes, MemoryUserSource } from '@basaltkit/auth'`);
-        imports.push(`import { env } from './env.js'`);
-        plugins.push(`authPlugin({
+        if (options.prisma) {
+            imports.push(`import { authPlugin, authRoutes, mfaRoutes } from '@basaltkit/auth'`);
+            imports.push(`import { prismaAuthStores } from '@basaltkit/auth-prisma'`);
+            imports.push(`import { env } from './env.js'`);
+            preamble.push(`/** Users, sessions, refresh tokens, email/reset tokens, MFA and API keys. */
+const authStores = prismaAuthStores(prisma)`);
+            plugins.push(`authPlugin({
+      users: authStores.users,
+      sessions: authStores.sessions,
+      refreshTokens: authStores.refreshTokens,
+      // Email verification and password reset.
+      tokens: authStores.tokens,
+      mfa: authStores.mfa,
+      secret: env.APP_SECRET,
+    })`);
+        }
+        else {
+            imports.push(`import { authPlugin, authRoutes, mfaRoutes, MemoryUserSource } from '@basaltkit/auth'`);
+            imports.push(`import { env } from './env.js'`);
+            plugins.push(`authPlugin({
       // Replace MemoryUserSource with your database-backed source (e.g.
       // @basaltkit/auth-sqlite or @basaltkit/auth-prisma). The default in-memory
       // MFA store is enough for the ready-made TOTP flow below.
       users: new MemoryUserSource(),
       secret: env.APP_SECRET,
     })`);
+        }
         // authRoutes(): register, login, logout, refresh, me, email verification and
         // password recovery. mfaRoutes(): TOTP enroll/activate/status/disable.
         routesExpression = '[...appRoutes, ...authRoutes(), ...mfaRoutes()]';
@@ -237,10 +346,21 @@ export function appTs(options) {
         // meta: { central: true }.
         imports[0] = `import { createApp, definePlugin } from '@basaltkit/core'`;
         imports.push(`import { TEAMS, teamsPlugin, tenantMembershipPlugin } from '@basaltkit/teams'`);
-        plugins.push(`teamsPlugin({
+        if (options.prisma) {
+            imports.push(`import { prismaTeamsStores } from '@basaltkit/teams-prisma'`);
+            preamble.push(`/** Memberships and invitations (\`team_memberships\`, \`team_invitations\`). */
+const teamStores = prismaTeamsStores(prisma)`);
+            plugins.push(`teamsPlugin({
+      memberships: teamStores.memberships,
+      invitations: teamStores.invitations,
+    })`);
+        }
+        else {
+            plugins.push(`teamsPlugin({
       // TODO: the default membership/invitation stores are in-memory — pass
       // persistent ones (memberships, invitations) before production.
     })`);
+        }
         plugins.push(`// Rejects authenticated requests for a tenant the user is not a member of.
       tenantMembershipPlugin()`);
         plugins.push(`// Dev-only seed: each new registrant joins the 'demo' tenant so the scaffold
@@ -250,12 +370,22 @@ export function appTs(options) {
     }
     if (options.billing) {
         imports.push(`import { definePlans, subscriptionsPlugin } from '@basaltkit/subscriptions'`);
+        if (options.prisma) {
+            imports.push(`import { prismaSubscriptionsStores } from '@basaltkit/subscriptions-prisma'`);
+            preamble.push(`/** Subscriptions, usage counters and webhook idempotency. */
+const subscriptionStores = prismaSubscriptionsStores(prisma)`);
+        }
         plugins.push(`subscriptionsPlugin({
       plans: definePlans({
         free: { price: 0, features: { projects: 3 } },
         pro: { price: { monthly: 29, yearly: 290 }, trial: '14d', features: { projects: 50 } },
       }),
-      fallbackPlan: 'free',
+      fallbackPlan: 'free',${options.prisma
+            ? `
+      store: subscriptionStores.store,
+      usage: subscriptionStores.usage,
+      webhooks: subscriptionStores.webhooks,`
+            : ''}
     })`);
     }
     if (options.cli) {
@@ -284,7 +414,7 @@ export function appTs(options) {
         : '';
     return `${imports.join('\n')}
 import { appRoutes } from './routes.js'
-
+${preamble.length > 0 ? `\n${preamble.join('\n\n')}\n` : ''}
 export interface BuildAppOptions {
   logLevel?: LogLevel
   pretty?: boolean${commandsField}
@@ -423,14 +553,368 @@ const app = buildApp({
 process.exit(await runCli({ app }))
 `;
 }
+/**
+ * The models each `@basaltkit/<domain>-prisma` package needs, copied VERBATIM
+ * from that package's reference `prisma/schema.prisma` — the same blocks
+ * `basalt prisma:sync` merges into an existing schema. The scaffold ships the
+ * merged result so a new app can run `prisma migrate dev` straight away;
+ * `tests/prisma.test.ts` fails if a package's reference schema drifts from the
+ * copy here.
+ */
+const PRISMA_MODELS = {
+    tenancy: `model Tenant {
+  id      String         @id
+  // The open tenant record ({ id, ...anything }) as JSON — attach whatever
+  // per-tenant fields you like; they round-trip unchanged.
+  data    Json
+  domains TenantDomain[]
+
+  @@map("tenants")
+}
+
+model TenantDomain {
+  domain   String @id
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId])
+  @@map("tenant_domains")
+}`,
+    auth: `model AuthUser {
+  id            String  @id
+  email         String  @unique
+  passwordHash  String
+  emailVerified Boolean @default(false)
+
+  @@map("auth_users")
+}
+
+model AuthSession {
+  id        String   @id
+  userId    String
+  expiresAt DateTime
+
+  @@index([userId])
+  @@map("auth_sessions")
+}
+
+model AuthRefreshToken {
+  token     String    @id
+  familyId  String
+  userId    String
+  expiresAt DateTime
+  usedAt    DateTime?
+
+  @@index([familyId])
+  @@index([userId])
+  @@map("auth_refresh_tokens")
+}
+
+model AuthToken {
+  token     String    @id
+  userId    String
+  purpose   String
+  expiresAt DateTime
+  usedAt    DateTime?
+
+  @@index([userId, purpose])
+  @@map("auth_tokens")
+}
+
+model AuthApiKey {
+  id         String    @id
+  name       String
+  prefix     String
+  hash       String    @unique
+  tenantId   String?
+  userId     String?
+  scopes     String[]
+  createdAt  DateTime
+  expiresAt  DateTime?
+  lastUsedAt DateTime?
+  revokedAt  DateTime?
+
+  @@index([tenantId])
+  @@index([userId])
+  @@map("auth_api_keys")
+}
+
+model AuthMfa {
+  userId        String   @id
+  secret        String
+  enabled       Boolean  @default(false)
+  recoveryCodes String[]
+  lastUsedStep  Int?
+
+  @@map("auth_mfa")
+}
+
+model AuthTokenVersion {
+  userId  String @id
+  version Int    @default(0)
+
+  @@map("auth_token_versions")
+}
+
+model AuthAccountLink {
+  // SHA-256 (hex) of provider + NUL + subject — the natural key hashed so the
+  // primary key stays short on MySQL (an OIDC \`sub\` may be 255 characters).
+  id        String   @id
+  provider  String
+  subject   String
+  userId    String
+  email     String
+  createdAt DateTime
+
+  @@index([userId])
+  @@map("auth_account_links")
+}
+
+model AuthPasskey {
+  // SHA-256 (hex) of the credential id (credential ids reach 1 023 bytes).
+  id           String    @id
+  credentialId String
+  userId       String
+  publicKey    String
+  counter      BigInt
+  transports   String?
+  deviceName   String?
+  createdAt    DateTime
+  lastUsedAt   DateTime?
+
+  @@index([userId])
+  @@map("auth_passkeys")
+}`,
+    teams: `model TeamMembership {
+  tenantId  String
+  userId    String
+  role      String
+  createdAt DateTime
+
+  @@id([tenantId, userId])
+  @@map("team_memberships")
+}
+
+model TeamInvitation {
+  id         String    @id
+  tenantId   String
+  email      String
+  role       String
+  token      String    @unique
+  invitedBy  String?
+  expiresAt  DateTime
+  acceptedAt DateTime?
+  revokedAt  DateTime?
+
+  @@index([tenantId, email])
+  @@map("team_invitations")
+}`,
+    subscriptions: `model Subscription {
+  billableId        String    @id
+  plan              String
+  period            String
+  status            String
+  trialEndsAt       DateTime?
+  cancelAtPeriodEnd Boolean?
+  canceledAt        DateTime?
+  gatewayRef        String?
+  pendingPlan       String?
+  pendingPeriod     String?
+
+  @@map("subscriptions")
+}
+
+model UsageCounter {
+  billableId String
+  feature    String
+  periodKey  String
+  value      Int    @default(0)
+
+  @@id([billableId, feature, periodKey])
+  @@map("usage_counters")
+}
+
+model WebhookEvent {
+  id     String   @id
+  seenAt DateTime @default(now())
+
+  @@map("webhook_events")
+}`,
+};
+/**
+ * `prisma/schema.prisma` — the datasource, the client generator, the models of
+ * every Basalt domain this app enables, and the app's own first model.
+ *
+ * Prisma 7 no longer takes the connection URL here (prisma.config.ts does), and
+ * the client needs an explicit `output`; src/db.ts imports it from there.
+ */
+export function prismaSchema(options) {
+    const domains = [];
+    if (options.tenancy)
+        domains.push(PRISMA_MODELS.tenancy);
+    if (options.auth)
+        domains.push(PRISMA_MODELS.auth);
+    if (enforcesMembership(options))
+        domains.push(PRISMA_MODELS.teams);
+    if (options.billing)
+        domains.push(PRISMA_MODELS.subscriptions);
+    return `// Prisma schema for ${options.name}.
+//
+// The blocks below the header are the reference models of the @basaltkit/*-prisma
+// packages this app uses — exactly what \`basalt prisma:sync\` merges. Add another
+// Basalt domain later by installing its \`*-prisma\` package and running
+// \`pnpm basalt prisma:sync\` (with --cli), then \`pnpm db:migrate\`.
+//
+// Apply changes with \`pnpm db:migrate\` (\`prisma migrate dev\`) — never
+// \`prisma db push\`: push writes no _prisma_migrations table, and src/app.ts
+// boots with prismaPlugin({ assertMigrated: true }), which requires it.
+
+generator client {
+  provider = "prisma-client-js"
+  output   = "../src/generated/prisma"
+}
+
+datasource db {
+  // The URL lives in prisma.config.ts (Prisma 7) — and in src/env.ts for the app.
+  provider = "postgresql"
+}
+${domains.map((block) => `\n${block}\n`).join('')}
+// ---------------------------------------------------------------------------
+// Your models.${options.tenancy
+        ? ` \`tenantId\` is the column tenancyExtension() (src/db.ts)
+// forces onto every query and every write, so keep it on everything a tenant
+// owns — and make cross-model foreign keys composite (@@unique([tenantId, id])
+// on the target) so the database refuses a cross-tenant link too.`
+        : ''}
+
+model Project {
+  id        String   @id @default(uuid())${options.tenancy ? '\n  tenantId  String' : ''}
+  name      String
+  createdAt DateTime @default(now())
+${options.tenancy ? '\n  @@index([tenantId])' : ''}
+  @@map("projects")
+}
+`;
+}
+/**
+ * `prisma.config.ts` — Prisma 7 reads the connection URL (and the seed command)
+ * from here instead of from schema.prisma. It applies the SAME precedence as
+ * src/env.ts: the app-prefixed name first, the bare `DATABASE_URL` only as a
+ * fallback, so the CLI and the running app can never mean different databases.
+ */
+export function prismaConfigTs(options) {
+    const prefix = envPrefix(options.name);
+    return `import { loadEnvFile } from 'node:process'
+import { defineConfig } from 'prisma/config'
+
+// Prisma loads no .env for you (neither does the app — see src/env.ts). This
+// mirrors \`node --env-file=.env\`: a variable already exported in your shell
+// still wins, the file only fills in what is missing.
+try {
+  loadEnvFile('.env')
+} catch {
+  // No .env file — the variables come from the environment.
+}
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',${options.tenancy
+        ? `
+  // Runs after \`prisma migrate dev\` / \`prisma migrate reset\`.
+  migrations: { seed: 'tsx prisma/seed.ts' },`
+        : ''}
+  datasource: {
+    // ${prefix}_DATABASE_URL first, bare DATABASE_URL only as a fallback: a
+    // stray DATABASE_URL from another project must never decide which database
+    // gets migrated.
+    url: process.env['${prefix}_DATABASE_URL'] ?? process.env['DATABASE_URL'] ?? '',
+  },
+})
+`;
+}
+/**
+ * `src/db.ts` — the Prisma client(s). Two bindings on purpose: the unscoped
+ * `prisma` for the framework stores (they key their own rows and run outside a
+ * tenant context) and, with tenancy, the `db` client the whole application uses,
+ * where every query is filtered by the request's tenant.
+ */
+export function dbTs(options) {
+    return `import { PrismaPg } from '@prisma/adapter-pg'${options.tenancy ? `\nimport { tenancyExtension } from '@basaltkit/prisma'` : ''}
+import { PrismaClient } from './generated/prisma/client.js'
+import { env } from './env.js'
+
+/**
+ * The base client. Prisma 7 talks to PostgreSQL through a driver adapter, so the
+ * connection string is passed here; prisma.config.ts hands the CLI the same one.
+ *
+ * ${options.tenancy
+        ? `This client is NOT tenant-scoped: the framework stores (auth, tenancy,
+ * teams, …) read and write their own tables, keyed by their own columns, and do
+ * it before a tenant is known (a login has no tenant yet). Application code
+ * should use \`db\` below — or \`db<PrismaClient>()\` from @basaltkit/prisma.`
+        : `Application code can also reach it with \`db<PrismaClient>()\` from
+ * @basaltkit/prisma, which returns the client registered by prismaPlugin.`}
+ */
+export const prisma = new PrismaClient({
+  adapter: new PrismaPg({ connectionString: env.DATABASE_URL }),
+})
+${options.tenancy
+        ? `
+/**
+ * The application client: tenancyExtension() forces the current tenant's
+ * \`tenantId\` onto every read, stamps it onto every write, and fails closed
+ * (MissingTenantError) when there is no tenant in context — application code
+ * cannot forget the filter. src/app.ts registers it with prismaPlugin, so
+ * \`db<PrismaClient>()\` inside a handler returns this one.
+ */
+export const db = prisma.$extends(tenancyExtension())
+`
+        : `
+/** Registered by prismaPlugin in src/app.ts. */
+export const db = prisma
+`}`;
+}
+/**
+ * `prisma/seed.ts` — creates the `demo` tenant the scaffolded resolvers expect
+ * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed` and after
+ * `prisma migrate dev` (prisma.config.ts declares it).
+ */
+export function prismaSeedTs(options) {
+    return `import { prismaTenantSource } from '@basaltkit/tenancy-prisma'
+import { prisma } from '../src/db.js'
+
+// The demo tenant the header and subdomain resolvers look for out of the box.
+// \`save\` is an upsert, so re-seeding is safe. Tenants are open records: add
+// whatever per-tenant fields you like — they round-trip unchanged.
+const tenants = prismaTenantSource(prisma)
+await tenants.save({ id: 'demo', name: 'Demo Tenant' })
+console.log('Seeded tenant "demo" for ${options.name}.')
+
+await prisma.$disconnect()
+`;
+}
 export function appTest(options) {
+    const prefix = envPrefix(options.name);
+    // With a database the app cannot boot without one: src/env.ts requires
+    // DATABASE_URL and prismaPlugin({ assertMigrated: true }) checks the schema.
+    // So the suite is gated on a configured database and imports src/app.ts
+    // lazily — an eager import would throw at module load instead of skipping.
     return `import { describe, expect, it } from 'vitest'
 import { FASTIFY } from '@basaltkit/fastify'
-import { buildApp } from '../src/app.js'
+${options.prisma
+        ? `
+// Needs a migrated database: set ${prefix}_DATABASE_URL (see .env.example), then
+// \`pnpm db:migrate${options.tenancy ? ' && pnpm db:seed' : ''}\`. Without one the suite skips instead of failing.
+const database = process.env['${prefix}_DATABASE_URL'] ?? process.env['DATABASE_URL']
+
+describe.skipIf(!database)('app', () => {
+  it('boots and responds on /health', async () => {
+    const { buildApp } = await import('../src/app.js')
+    const app = await buildApp({ logLevel: 'silent' }).boot()`
+        : `import { buildApp } from '../src/app.js'
 
 describe('app', () => {
   it('boots and responds on /health', async () => {
-    const app = await buildApp({ logLevel: 'silent' }).boot()
+    const app = await buildApp({ logLevel: 'silent' }).boot()`}
     const server = app.container.get(FASTIFY)
 
     const index = await server.inject({ method: 'GET', url: '/' })
@@ -459,6 +943,7 @@ export function readme(options) {
         'typed routes with Zod validation',
         'structured logging with request/tenant context',
         'typed domain events',
+        ...(options.prisma ? ['PostgreSQL persistence through Prisma (migrations + tenant-scoped client)'] : []),
         ...(options.tenancy ? ['multi-tenancy (header + subdomain resolvers)'] : []),
         ...(options.auth ? ['authentication (register/login/refresh/me)'] : []),
         ...(options.billing ? ['subscriptions with plans and feature limits'] : []),
@@ -475,11 +960,64 @@ Included: ${features.join(' · ')}.
 ## Getting started
 
 \`\`\`bash
-pnpm install
+pnpm install${options.prisma
+        ? `
+# point ${envPrefix(options.name)}_DATABASE_URL at a PostgreSQL database (.env.example), then
+pnpm db:migrate # create the tables${options.tenancy ? ` (runs the seed too)` : ''}`
+        : ''}
 pnpm dev        # API on http://localhost:3000
 pnpm test
 \`\`\`
+${options.prisma
+        ? `
+## Database
+
+PostgreSQL through [Prisma](https://www.prisma.io). \`prisma/schema.prisma\` holds
+the models this app needs — the reference models of the \`@basaltkit/*-prisma\`
+packages it uses, plus your own \`Project\` at the end.
+
+\`\`\`bash
+pnpm db:migrate     # prisma migrate dev  — change the schema, write a migration${options.tenancy
+            ? `
+pnpm db:seed        # the 'demo' tenant the resolvers expect (also run by db:migrate)`
+            : ''}
+pnpm db:generate    # prisma generate — refresh src/generated/prisma (also runs on install)
+pnpm db:deploy      # prisma migrate deploy — apply pending migrations in production
+\`\`\`
+
+**Never use \`prisma db push\` on this project.** \`src/app.ts\` boots with
+\`prismaPlugin({ client: db, assertMigrated: true })\`, which refuses to start
+unless the database it reached has the \`_prisma_migrations\` table — the one
+\`migrate dev\` / \`migrate deploy\` write and \`db push\` does not. That check is
+what turns "wrong \`DATABASE_URL\`" (a shell that exported another project's, a
+typo in the database name) into a boot error naming the database and host,
+instead of a 500 on the first request that touches a missing table.
+
+\`src/db.ts\` exports two clients:
 
+- \`prisma\` — unscoped. The framework stores (auth${options.tenancy ? ', tenancy' : ''}${enforcesMembership(options) ? ', teams' : ''}${options.billing ? ', subscriptions' : ''}) use it: they key
+  their own tables and run before a tenant is known.${options.tenancy
+            ? `
+- \`db\` — \`prisma.$extends(tenancyExtension())\`. Registered with \`prismaPlugin\`,
+  so \`db<PrismaClient>()\` inside a handler returns a client that filters every
+  read by the request's tenant, stamps every write, and throws instead of running
+  unscoped. Keep \`tenantId\` on every model a tenant owns.`
+            : ''}
+${options.cli
+            ? `
+Adding another Basalt domain later (audit, comments, notifications, …): install
+its \`@basaltkit/<domain>-prisma\` package, run \`pnpm basalt prisma:sync\` to merge
+its models into the schema, then \`pnpm db:migrate\`.
+`
+            : `
+Adding another Basalt domain later (audit, comments, notifications, …): install
+its \`@basaltkit/<domain>-prisma\` package, copy the models from its
+\`schema.prisma\` into yours, then \`pnpm db:migrate\`. (With the \`basalt\` CLI —
+scaffold with \`--cli\` — \`pnpm basalt prisma:sync\` does the merge for you.)
+`}
+\`pnpm test\` skips the generated suite when no database is configured.
+`
+        : ''}
 ## Environment
 
 \`src/env.ts\` validates \`process.env\` — nothing loads \`.env\` for you. Copy
@@ -487,7 +1025,7 @@ pnpm test
 export the variables.
 
 The variables are **app-prefixed**: \`${envPrefix(options.name)}_PORT\`,
-\`${envPrefix(options.name)}_HOST\`, \`${envPrefix(options.name)}_LOG_LEVEL\`${options.auth ? `, \`${envPrefix(options.name)}_APP_SECRET\`` : ''}. \`NODE_ENV\` is never prefixed.
+\`${envPrefix(options.name)}_HOST\`, \`${envPrefix(options.name)}_LOG_LEVEL\`${options.auth ? `, \`${envPrefix(options.name)}_APP_SECRET\`` : ''}${options.prisma ? `, \`${envPrefix(options.name)}_DATABASE_URL\`` : ''}. \`NODE_ENV\` is never prefixed.
 
 Why: **\`--env-file\` never overrides a variable that is already exported.** In a
 shell where another project exported \`DATABASE_URL\` (or \`PORT\`), an app reading
@@ -495,8 +1033,13 @@ the generic name boots against THAT value and only fails on the first request
 that touches it. \`src/env.ts\` therefore passes \`prefix: '${envPrefix(options.name)}'\` to
 \`defineEnv\`: each variable is read as \`${envPrefix(options.name)}_<NAME>\` first and
 **falls back** to the bare \`<NAME>\`, so a deployment that already exports the
-generic names keeps booting while a stray one in your shell loses. Add a
-database and \`DATABASE_URL\` is read as \`${envPrefix(options.name)}_DATABASE_URL\`.
+generic names keeps booting while a stray one in your shell loses.${options.prisma
+        ? ` That is
+exactly how \`DATABASE_URL\` is read here (\`${envPrefix(options.name)}_DATABASE_URL\` first), and
+\`prisma.config.ts\` applies the same precedence — so \`pnpm db:migrate\` and the
+running app can never mean two different databases.`
+        : ` Add a
+database and \`DATABASE_URL\` is read as \`${envPrefix(options.name)}_DATABASE_URL\`.`}
 
 To drop the fallback entirely (prefixed names only), write
 \`prefix: { value: '${envPrefix(options.name)}', fallback: false }\`. When in doubt about what
@@ -607,14 +1150,18 @@ export function dockerignore() {
 **/.DS_Store
 `;
 }
-export function gitignore() {
+export function gitignore(options) {
     return `node_modules/
 dist/
 .env
 .env.*
 !.env.example
 *.log
-`;
+${options.prisma
+        ? `# Generated by \`prisma generate\` (runs on install) — never edit or commit it.
+src/generated/
+`
+        : ''}`;
 }
 /**
  * pnpm settings: esbuild's build script is required by tsx;

package/dist/versions.js

@@ -4,21 +4,25 @@
 export const SCAFFOLD_VERSIONS = {
     '@basaltkit/admin': '^2.0.0',
     '@basaltkit/admin-shadcn': '^1.1.0',
-    '@basaltkit/ai-mcp': '^0.1.0',
-    '@basaltkit/auth': '^3.1.0',
+    '@basaltkit/ai-mcp': '^0.2.0',
+    '@basaltkit/auth': '^4.0.0',
+    '@basaltkit/auth-prisma': '^2.0.0',
     '@basaltkit/cli': '^1.2.0',
     '@basaltkit/config': '^1.1.0',
-    '@basaltkit/core': '^1.4.0',
+    '@basaltkit/core': '^1.5.0',
     '@basaltkit/env': '^3.1.0',
     '@basaltkit/events': '^1.3.0',
-    '@basaltkit/fastify': '^2.2.0',
+    '@basaltkit/fastify': '^2.5.0',
     '@basaltkit/generator': '^1.5.0',
     '@basaltkit/logger': '^1.3.0',
-    '@basaltkit/mcp': '^3.0.0',
-    '@basaltkit/prisma': '^2.1.0',
+    '@basaltkit/mcp': '^4.0.0',
+    '@basaltkit/prisma': '^3.0.0',
     '@basaltkit/sdk': '^2.1.0',
-    '@basaltkit/subscriptions': '^4.0.0',
-    '@basaltkit/teams': '^3.0.0',
-    '@basaltkit/tenancy': '^2.0.0',
+    '@basaltkit/subscriptions': '^5.0.0',
+    '@basaltkit/subscriptions-prisma': '^3.0.0',
+    '@basaltkit/teams': '^4.0.0',
+    '@basaltkit/teams-prisma': '^1.1.0',
+    '@basaltkit/tenancy': '^3.0.0',
+    '@basaltkit/tenancy-prisma': '^2.0.0',
     '@basaltkit/testing': '^2.0.0',
 };

package/dist/wizard.d.ts

@@ -1,6 +1,6 @@
 import type { PackageManager } from './index.js';
 import { type Choice, type Prompter } from './prompt.js';
-export type FeatureKey = 'tenancy' | 'auth' | 'billing' | 'ui' | 'cli' | 'mcp';
+export type FeatureKey = 'tenancy' | 'auth' | 'billing' | 'ui' | 'cli' | 'mcp' | 'prisma';
 /** The feature toggles offered in the "custom" preset (and shown in the summary). */
 export declare const FEATURES: Choice<FeatureKey>[];
 interface Preset {
@@ -21,6 +21,7 @@ export interface WizardResult {
     ui: boolean;
     cli: boolean;
     mcp: boolean;
+    prisma: boolean;
     pm: PackageManager;
     install: boolean;
     git: boolean;

package/dist/wizard.js

@@ -7,11 +7,12 @@ export const FEATURES = [
     { value: 'ui', label: 'Web UI', hint: 'React + shadcn + SDK (pnpm workspace)' },
     { value: 'cli', label: 'basalt CLI', hint: 'code generators + commands' },
     { value: 'mcp', label: 'MCP server', hint: 'expose routes as AI-agent tools (/mcp)' },
+    { value: 'prisma', label: 'Database', hint: 'PostgreSQL via Prisma (migrations + real stores)' },
 ];
 export const PRESETS = [
-    { value: 'saas', label: 'SaaS starter', hint: 'tenancy + auth + billing + CLI', features: ['tenancy', 'auth', 'billing', 'cli'] },
+    { value: 'saas', label: 'SaaS starter', hint: 'tenancy + auth + billing + database + CLI', features: ['tenancy', 'auth', 'billing', 'prisma', 'cli'] },
     { value: 'api', label: 'API only', hint: 'auth + MCP, no tenancy or UI', features: ['auth', 'mcp'] },
-    { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'ui', 'cli', 'mcp'] },
+    { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'prisma', 'ui', 'cli', 'mcp'] },
     { value: 'minimal', label: 'Minimal', hint: 'no batteries, add them later', features: [] },
     { value: 'custom', label: 'Custom', hint: 'pick features yourself', features: null },
 ];
@@ -90,6 +91,7 @@ export async function runWizard(prompter, options = {}) {
         ui: featureSet.has('ui'),
         cli: featureSet.has('cli'),
         mcp: featureSet.has('mcp'),
+        prisma: featureSet.has('prisma'),
         pm,
         install,
         git,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -21,26 +21,35 @@
     "dist"
   ],
   "devDependencies": {
+    "@prisma/adapter-pg": "^7.10.0",
+    "@prisma/client": "^7.10.0",
     "@types/node": "^26.6.1",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.0",
+    "prisma": "^7.10.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
     "zod": "^4.6.5",
-    "@basaltkit/config": "^1.1.2",
-    "@basaltkit/auth": "^3.1.0",
+    "@basaltkit/auth": "^4.0.0",
+    "@basaltkit/auth-prisma": "^2.0.0",
     "@basaltkit/cli": "^1.2.5",
-    "@basaltkit/env": "^3.1.0",
-    "@basaltkit/core": "^1.4.0",
+    "@basaltkit/config": "^1.1.2",
+    "@basaltkit/core": "^1.5.0",
+    "@basaltkit/env": "^3.1.1",
     "@basaltkit/events": "^1.3.0",
-    "@basaltkit/fastify": "^2.2.0",
+    "@basaltkit/fastify": "^2.5.0",
     "@basaltkit/generator": "^1.5.0",
     "@basaltkit/logger": "^1.3.0",
-    "@basaltkit/mcp": "^3.0.0",
-    "@basaltkit/subscriptions": "^4.0.0",
-    "@basaltkit/teams": "^3.0.1",
-    "@basaltkit/tenancy": "^2.0.0",
-    "@basaltkit/tsconfig": "^0.24.0",
-    "@basaltkit/testing": "^2.0.2",
-    "@basaltkit/prisma": "^2.1.0"
+    "@basaltkit/mcp": "^4.0.0",
+    "@basaltkit/prisma": "^3.0.0",
+    "@basaltkit/subscriptions": "^5.0.0",
+    "@basaltkit/subscriptions-prisma": "^3.0.0",
+    "@basaltkit/teams": "^4.0.0",
+    "@basaltkit/teams-prisma": "^1.1.0",
+    "@basaltkit/tenancy": "^3.0.0",
+    "@basaltkit/tenancy-prisma": "^2.0.0",
+    "@basaltkit/testing": "^2.0.3",
+    "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
     "access": "public"