create-basalt 1.6.0 → 1.8.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
@@ -135,19 +137,19 @@ Always:
 my-app/
 ├── package.json          # scripts: dev, start, test, typecheck (+ basalt with --cli)
 ├── tsconfig.json         # strict TypeScript, ESM
-├── .env.example          # PORT, HOST, LOG_LEVEL, NODE_ENV (+ APP_SECRET with auth) + the --env-file precedence warning
+├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the --env-file precedence warning
 ├── .gitignore
 ├── README.md             # instructions adapted to the chosen options
 ├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
 ├── src/
-│   ├── env.ts            # environment variables validated with Zod (@basaltkit/env)
+│   ├── env.ts            # environment variables validated with Zod (@basaltkit/env), app-prefixed
 │   ├── app.ts            # buildApp() with the chosen plugins
 │   ├── routes.ts         # GET / (friendly index) and GET /health
 │   └── server.ts         # startup + clean shutdown on SIGINT/SIGTERM
 └── 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
@@ -176,7 +216,28 @@ With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies
 
 ### Environment variables and `--env-file`
 
-Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, the app boots against that value and only fails on the first request that touches it. The generated `.env.example` and README say so and suggest an app-specific prefix derived from the project name (`my-saas` → `MY_SAAS_DATABASE_URL`).
+Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
+
+The scaffold closes that trap instead of only warning about it: `src/env.ts` passes an **app-specific prefix** derived from the project name (`my-saas` → `MY_SAAS`) to `defineEnv`, and `.env.example` uses the prefixed names.
+
+```ts
+// src/env.ts (generated)
+export const env = defineEnv(
+  { PORT: z.coerce.number().default(3000), /* … */ },
+  { prefix: 'MY_SAAS' },
+)
+```
+
+```bash
+# .env.example (generated)
+MY_SAAS_PORT=3000
+MY_SAAS_HOST=0.0.0.0
+MY_SAAS_LOG_LEVEL=info
+NODE_ENV=development          # never prefixed — a Node-wide convention
+# MY_SAAS_APP_SECRET=         # with auth
+```
+
+Each variable is read as `MY_SAAS_<NAME>` first and **falls back** to the bare `<NAME>`, so a deployment that already exports the generic names keeps booting — while a stray `PORT` in your shell no longer wins. The rest of the app is unchanged: the keys stay bare (`env.PORT`). To require the prefixed names only, edit the generated file to `prefix: { value: 'MY_SAAS', fallback: false }`. Full rules: [`@basaltkit/env`](https://github.com/basaltkit/basalt/tree/main/packages/env#app-specific-prefix-prefix).
 
 ### Programmatic usage (Advanced)
 
@@ -219,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) |
 
@@ -246,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)
@@ -267,10 +329,24 @@ Outside an interactive terminal (no TTY) the questions are skipped. Always pass
 Automatic installation failed (network, Node version, etc.). Go into the folder and run `pnpm install` (or the indicated manager) to see the real error.
 
 **I started the app and `GET /auth/login` gives a secret error.**
-With auth on, `src/env.ts` requires `APP_SECRET` with at least 16 characters (there's a development default `change-me-in-production--`). Copy `.env.example` to `.env` and set your own secret before going to production.
+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`. Check `env | grep DATABASE_URL`, start with `env -u DATABASE_URL pnpm dev`, and prefer app-prefixed names (see *Environment variables and `--env-file`*).
+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`*.
 
 **`pnpm basalt …` starts by running `pnpm install` (or fails offline).**
 pnpm 11's `verifyDepsBeforeRun` (default `install`). Run `node_modules/.bin/tsx bin/basalt.ts …` instead, or set `verifyDepsBeforeRun: warn` in `pnpm-workspace.yaml`.
@@ -286,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 —