@webjsdev/cli 0.10.17 → 0.10.18

package/README.md

@@ -40,15 +40,15 @@ Both `webjs create` and `create-webjs-app` auto-install dependencies in the new
 ```sh
 webjs create <name>            # scaffold a full-stack app (default)
 webjs create <name> --template api   # backend-only API app
-webjs create <name> --template saas  # auth + dashboard + Prisma User model
+webjs create <name> --template saas  # auth + dashboard + Drizzle User model
 
-webjs dev                      # dev server with live reload (prefer `npm run dev`, which runs the predev prisma generate hook)
+webjs dev                      # dev server with live reload (runs webjs.dev.before, e.g. webjs db migrate, then serves; npm run dev is a thin alias)
 webjs start                    # production server (no build step, serves source directly)
 webjs check                    # validate source-code conventions (CI gate)
 webjs doctor                   # verify the project/toolchain setup (local onboarding, not CI)
 webjs test                     # run server + browser tests
 webjs vendor pin [--download]  # pin client deps to a committable importmap (offline/reproducible)
-webjs db <prisma-subcommand>   # prisma passthrough (saas template)
+webjs db <generate|migrate|push|studio|seed>   # drizzle-kit passthrough (+ seed)
 
 webjs ui init                  # initialise @webjsdev/ui in this project
 webjs ui add <names...>        # copy components from the registry (https://ui.webjs.dev/registry/<name>.json)

package/bin/webjs.js

@@ -49,13 +49,15 @@ const USAGE = `webjs commands:
   webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
-  webjs create <name> [--template full-stack|api|saas] [--no-install]  Scaffold a new webjs app
-                                                  (only 3 templates exist. default: full-stack with Prisma+SQLite)
+  webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--no-install]  Scaffold a new webjs app
+                                                  (only 3 templates exist. default: full-stack, Drizzle, --db sqlite)
                                                   Auto-runs the detected package manager's install in the new dir
                                                   unless --no-install is passed.
-  webjs db generate                               Run \`prisma generate\`
-  webjs db migrate [name]                         Run \`prisma migrate dev\`
-  webjs db studio                                 Run \`prisma studio\`
+  webjs db generate                               Generate a SQL migration from the schema (drizzle-kit generate)
+  webjs db migrate                                Apply pending migrations (drizzle-kit migrate)
+  webjs db push                                   Push the schema straight to the dev DB (drizzle-kit push)
+  webjs db studio                                 Open the database browser (drizzle-kit studio)
+  webjs db seed                                   Run the app's db/seed.server.ts
   webjs ui <subcmd>                               AI-first component library CLI
                                                   (init / add / list / view / diff / info)
                                                   Requires @webjsdev/ui installed in the project
@@ -73,6 +75,42 @@ function flag(args, name, def) {
   return args[i + 1];
 }
 
+/**
+ * Run the configured `before` steps (#550) for a phase, aborting the boot on
+ * the first failure. The orchestration lives in `lib/run-tasks.js` (pure,
+ * unit-tested); this owns the phase-prefixed logging + the non-zero exit (a
+ * failed generate/migrate must not serve stale code/schema).
+ *
+ * @param {string} phase 'dev' | 'start' (for the log line)
+ * @param {string[]} steps
+ * @param {string} cwd
+ */
+async function runPhaseBeforeSteps(phase, steps, cwd) {
+  const { runBeforeSteps } = await import('../lib/run-tasks.js');
+  const r = await runBeforeSteps(steps, cwd, {
+    onStep: (step) => console.log(`webjs ${phase}: running before-step \`${step}\`…`),
+  });
+  if (!r.ok) {
+    console.error(`webjs ${phase}: before-step failed (exit ${r.code}): ${r.step}`);
+    process.exit(r.code);
+  }
+}
+
+/**
+ * Spawn the configured dev `parallel` tasks (#550) with phase-prefixed logging,
+ * delegating the spawn + teardown to `lib/run-tasks.js`'s `startParallelTasks`.
+ *
+ * @param {string[]} commands
+ * @param {string} cwd
+ * @returns {Promise<() => void>} the killer
+ */
+async function startDevParallelTasks(commands, cwd) {
+  const { startParallelTasks } = await import('../lib/run-tasks.js');
+  return startParallelTasks(commands, cwd, {
+    onStart: (cmd) => console.log(`webjs dev: starting parallel task \`${cmd}\`…`),
+  });
+}
+
 async function main() {
   // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
   // Run before any subcommand so an older Node fails fast with a clear,
@@ -98,14 +136,18 @@ async function main() {
         break;
       }
 
-      // A bare `webjs dev` (not `npm run dev`) skips the `predev` hook, so a
-      // Prisma app boots against an ungenerated client and crashes with no
-      // hint (#452). Detect that here, in the PARENT only, so the message
-      // prints once rather than on every watch restart. Scoped to Prisma apps;
-      // a non-Prisma app sees nothing. A hint, not an auto-run.
-      const { prismaDevHint } = await import('../lib/prisma-preflight.js');
-      const hint = prismaDevHint(process.cwd());
-      if (hint) console.error(hint);
+      // Run the configured dev orchestration in the PARENT only (#550), so a
+      // bare `webjs dev` matches `npm run dev`. `dev.before` (one-shot tasks)
+      // runs to completion first; `dev.parallel` (Tailwind's
+      // watcher, etc.) then runs as children alongside the server. Spawned once
+      // here, NOT in the watch child (which re-execs on every restart). Torn
+      // down on exit so a watcher cannot outlive the server.
+      const { readAppTasks } = await import('../lib/app-tasks.js');
+      const devTasks = readAppTasks(process.cwd());
+      await runPhaseBeforeSteps('dev', devTasks.dev.before, process.cwd());
+      const killTasks = await startDevParallelTasks(devTasks.dev.parallel, process.cwd());
+      process.on('SIGINT', () => { killTasks(); process.exit(0); });
+      process.on('SIGTERM', () => { killTasks(); process.exit(0); });
 
       // Decide how to run: in-process (`--no-hot`), or re-exec'd under the host
       // runtime's hot-reload supervisor (`node --watch` on Node, `bun --hot` on
@@ -124,6 +166,7 @@ async function main() {
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
         await startServer({ appDir: process.cwd(), port, dev: true });
+        killTasks();
         break;
       }
 
@@ -132,7 +175,7 @@ async function main() {
         cwd: process.cwd(),
         env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
       });
-      child.on('exit', (code) => process.exit(code ?? 0));
+      child.on('exit', (code) => { killTasks(); process.exit(code ?? 0); });
       break;
     }
     case 'start': {
@@ -140,6 +183,11 @@ async function main() {
       // Load `.env` BEFORE resolving the port so a `PORT` set there wins over
       // the 8080 default (#447), same as for `dev`.
       loadAppEnv(process.cwd());
+      // Run the configured `start.before` steps (e.g. `webjs db migrate`)
+      // before serving (#550), so a bare `webjs start` is not a degraded run
+      // that skips the `prestart` hook. Aborts the boot on a failed step.
+      const { readAppTasks } = await import('../lib/app-tasks.js');
+      await runPhaseBeforeSteps('start', readAppTasks(process.cwd()).start.before, process.cwd());
       const port = resolvePort(flag(rest, '--port'));
       await startServer({ appDir: process.cwd(), port, dev: false });
       break;
@@ -147,10 +195,28 @@ async function main() {
     case 'db': {
       const sub = rest[0];
       const args = rest.slice(1);
-      const map = { generate: ['generate'], migrate: ['migrate', 'dev', ...args], studio: ['studio'] };
-      const prismaArgs = map[sub];
-      if (!prismaArgs) { console.error('Unknown db subcommand.\n' + USAGE); process.exit(1); }
-      const child = spawn('npx', ['prisma', ...prismaArgs], { stdio: 'inherit', cwd: process.cwd() });
+      // `webjs db seed` runs the app's own seed script directly (not a
+      // drizzle-kit command); Drizzle has no codegen, so there is no
+      // `generate`-the-client step, only schema-to-SQL `generate`.
+      if (sub === 'seed') {
+        const { existsSync } = await import('node:fs');
+        const seedFile = ['db/seed.server.ts', 'db/seed.server.js']
+          .map((p) => join(process.cwd(), p)).find(existsSync);
+        if (!seedFile) {
+          console.error('No db/seed.server.ts found in this app.');
+          process.exit(1);
+        }
+        const child = spawn(process.execPath, [seedFile], { stdio: 'inherit', cwd: process.cwd() });
+        child.on('exit', (code) => process.exit(code ?? 0));
+        break;
+      }
+      // generate (schema -> SQL migration), migrate (apply), push (dev
+      // schema sync), studio. All wrap drizzle-kit; the verbose name stays
+      // hidden behind `webjs db`.
+      const map = { generate: ['generate'], migrate: ['migrate'], push: ['push'], studio: ['studio'] };
+      const kitArgs = map[sub];
+      if (!kitArgs) { console.error('Unknown db subcommand.\n' + USAGE); process.exit(1); }
+      const child = spawn('npx', ['drizzle-kit', ...kitArgs, ...args], { stdio: 'inherit', cwd: process.cwd() });
       child.on('exit', (code) => process.exit(code ?? 0));
       break;
     }
@@ -405,18 +471,18 @@ async function main() {
         console.error(`Error: unknown template '${template}'.
 
 Only three scaffolds exist:
-  full-stack   (default): pages + components + API + Prisma/SQLite.
+  full-stack   (default): pages + components + API + Drizzle/SQLite.
                 Pick this for any app the user describes in product terms
                 (todo app, blog, dashboard, marketplace, social feed, …).
   api          backend-only: route handlers + modules, no pages/SSR.
                 Pick this only if the user explicitly asks for an HTTP/JSON
                 API with no UI.
-  saas         auth + login/signup + protected dashboard + Prisma User
+  saas         auth + login/signup + protected dashboard + Drizzle User
                 model. Pick this only if the user explicitly asks for auth
                 or a SaaS-shaped product.
 
 The scaffold is a starting point. Replace the example layout/page/
-components/schema with the actual app the user requested. Use Prisma +
+components/schema with the actual app the user requested. Use Drizzle +
 SQLite for persistence (already wired up). Never store app data in JSON
 files.
 
@@ -424,8 +490,10 @@ Full docs: https://docs.webjs.com`);
         process.exit(1);
       }
       const noInstall = rest.includes('--no-install');
+      // --db picks the database dialect: sqlite (default) or postgres.
+      const db = flag(rest, '--db', 'sqlite');
       const { scaffoldApp } = await import('../lib/create.js');
-      await scaffoldApp(name, process.cwd(), { template, install: !noInstall });
+      await scaffoldApp(name, process.cwd(), { template, db, install: !noInstall });
       break;
     }
     case 'vendor': {

package/lib/app-tasks.js

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Read the dev/start task orchestration from an app's `package.json` `"webjs"`
+ * block (#550). This is what lets `webjs dev` / `webjs start` behave identically
+ * to `npm run dev` / `npm run start`: the orchestration (Tailwind's watcher, a
+ * `db migrate` before prod boot) moves OUT of `concurrently` + `pre*` npm hooks
+ * and INTO the framework primitive, so a bare `webjs dev` is not a degraded run.
+ *
+ * Shape:
+ *   "webjs": {
+ *     "dev":   {
+ *       "before":   ["webjs db migrate"],
+ *       "parallel": ["tailwindcss -i ./public/input.css -o ./public/tailwind.css --watch"]
+ *     },
+ *     "start": { "before": ["webjs db migrate"] }
+ *   }
+ *
+ * `before` commands run sequentially to completion BEFORE the server boots (the
+ * old `predev` / `prestart` hooks: a one-shot `webjs db migrate`).
+ * `parallel` (dev only) commands run as long-lived child processes ALONGSIDE the
+ * server (the old `concurrently` watchers: Tailwind). Returns normalized arrays
+ * (never undefined) so callers iterate without guards, and a missing/empty
+ * config yields empty arrays so a plain app runs `webjs dev`/`start` unchanged.
+ *
+ * Pure (reads one file, never spawns / prints / exits) so it is unit-testable
+ * without a process, matching `lib/port.js` and `lib/dev-supervisor.js`.
+ *
+ * @param {string} appDir
+ * @param {(p: string) => string} [readFile] injectable reader for tests
+ * @returns {{ dev: { before: string[], parallel: string[] }, start: { before: string[] } }}
+ */
+export function readAppTasks(appDir, readFile) {
+  const read = readFile || ((p) => readFileSync(p, 'utf8'));
+  let pkg = {};
+  try {
+    pkg = JSON.parse(read(join(appDir, 'package.json')));
+  } catch {
+    // No package.json, or unparseable: a plain run with no orchestration.
+    return emptyTasks();
+  }
+  const webjs = pkg && typeof pkg === 'object' ? pkg.webjs : null;
+  if (!webjs || typeof webjs !== 'object') return emptyTasks();
+
+  /** Keep only non-empty string entries; drop anything else defensively. */
+  const cmds = (v) =>
+    Array.isArray(v) ? v.filter((s) => typeof s === 'string' && s.trim().length > 0) : [];
+
+  return {
+    dev: {
+      before: cmds(webjs.dev && webjs.dev.before),
+      parallel: cmds(webjs.dev && webjs.dev.parallel),
+    },
+    start: { before: cmds(webjs.start && webjs.start.before) },
+  };
+}
+
+/** @returns {{ dev: { before: string[], parallel: string[] }, start: { before: string[] } }} */
+function emptyTasks() {
+  return { dev: { before: [], parallel: [] }, start: { before: [] } };
+}

package/lib/create.js

@@ -249,6 +249,15 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   }
   const isApi = template === 'api';
   const isSaas = template === 'saas';
+
+  // Database dialect (#563): sqlite (default) or postgres. Drizzle is the ORM;
+  // the schema/queries/actions are identical across dialects, only db/columns
+  // + db/connection + the driver dep differ.
+  const dialect = opts.db || 'sqlite';
+  const VALID_DIALECTS = ['sqlite', 'postgres'];
+  if (!VALID_DIALECTS.includes(dialect)) {
+    throw new Error(`Unknown --db '${dialect}'. Only ${VALID_DIALECTS.join(' / ')} are supported.`);
+  }
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -264,7 +273,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'modules',
     'lib',
     'public',
-    'prisma',
+    'db',
     'test/unit',
     'test/e2e',
   ];
@@ -278,8 +287,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     type: 'module',
     private: true,
     scripts: {
-      predev: 'prisma generate',
-      prestart: 'prisma migrate deploy',
+      // No `predev` / `prestart` hooks (#550): the `webjs` block below holds
+      // the start orchestration (`webjs db migrate`), run INSIDE `webjs start`,
+      // so `npm run start` (a thin alias) behaves identically. Drizzle has no
+      // codegen, so there is no dev `before` step.
       dev: 'webjs dev',
       start: 'webjs start',
       test: 'webjs test',
@@ -292,18 +303,24 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // vendor pins, @webjsdev versions, git hook). Local tool, NOT a CI gate
       // (its env-drift + network pin-freshness checks would make CI flaky).
       doctor: 'webjs doctor',
-      'db:migrate': 'prisma migrate dev',
-      'db:generate': 'prisma generate',
-      'db:studio': 'prisma studio',
+      'db:generate': 'webjs db generate',
+      'db:migrate': 'webjs db migrate',
+      'db:push': 'webjs db push',
+      'db:studio': 'webjs db studio',
+      'db:seed': 'webjs db seed',
     },
     dependencies: {
-      '@prisma/client': '^6.0.0',
+      // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
+      // for relations v2. The SQLite/Postgres driver below is dialect-picked.
+      'drizzle-orm': '^1.0.0-rc.3',
+      ...(dialect === 'postgres' ? { pg: '^8.13.0' } : { 'better-sqlite3': '^12.11.1' }),
       '@webjsdev/cli': 'latest',
       '@webjsdev/core': 'latest',
       '@webjsdev/server': 'latest',
     },
     devDependencies: {
-      prisma: '^6.0.0',
+      'drizzle-kit': '^1.0.0-rc.3',
+      ...(dialect === 'postgres' ? { '@types/pg': '^8.11.0' } : {}),
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
       // to type-check the app.
@@ -330,6 +347,18 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // into components/ui/ (they import @webjsdev/core, not the kit), and the
       // CLI resolves @webjsdev/ui from its own install.
     },
+    // Start task orchestration (#550). `webjs start` reads `start.before` and
+    // runs it in-process, so `npm run start` (a thin alias above) behaves
+    // identically. Drizzle has no codegen, so there is no dev `before` step;
+    // production applies pending migrations via `webjs db migrate`. The scaffold
+    // uses the Tailwind browser runtime (no CSS build step), so there is no dev
+    // `parallel` watcher here; an app that adds the Tailwind CLI puts its
+    // `--watch` command under `webjs.dev.parallel`.
+    webjs: {
+      // Drizzle has no codegen, so there is no dev `before` step. Production
+      // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
+      start: { before: ['webjs db migrate'] },
+    },
   }, null, 2) + '\n');
 
   await writeFile(join(appDir, 'tsconfig.json'), JSON.stringify({
@@ -381,7 +410,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'middleware.ts',
       '.webjs/routes.d.ts',
     ],
-    exclude: ['node_modules', '.webjs/vendor', 'prisma/migrations'],
+    exclude: ['node_modules', '.webjs/vendor', 'db/migrations'],
   }, null, 2) + '\n');
 
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
@@ -398,8 +427,8 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // Environment variables
     '.env.example',
     // Project-level gitignore (node_modules, .webjs, .env, OS junk).
-    // The Prisma dev.db rule is appended programmatically below so it
-    // only appears in templates that actually use SQLite.
+    // The SQLite dev.db rule is appended programmatically below so it
+    // only appears for the sqlite dialect.
     '.gitignore',
     // Git hooks (blocks commits on main)
     '.hooks/pre-commit',
@@ -471,62 +500,172 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   const preCommitPath = join(appDir, '.hooks', 'pre-commit');
   if (existsSync(preCommitPath)) await chmod(preCommitPath, 0o755);
 
-  // --- Prisma schema + client singleton (all templates) ---
+  // --- Drizzle db layer (all templates), dialect-selected (#563) ---
+  //
+  // The schema, queries, and actions are identical across dialects; only
+  // db/columns.server.ts + db/connection.server.ts + drizzle.config.ts + the
+  // driver dep differ. Switching dialect (e.g. SQLite in dev, Postgres in
+  // prod) is a config + module swap, not a code rewrite. Pinned to drizzle-orm
+  // 1.0.0-rc.3 (relations v2). See research #562.
 
-  await writeFile(join(appDir, 'prisma', 'schema.prisma'), `generator client {
-  provider = "prisma-client-js"
-}
+  const columnsSqlite = `import { sqliteTableCreator, integer, text, real, blob, index as _index } from 'drizzle-orm/sqlite-core';
+import type { SQLiteColumn } from 'drizzle-orm/sqlite-core';
+import { getTableName, type Table } from 'drizzle-orm';
 
-datasource db {
-  // Defaults to SQLite at ./prisma/dev.db. Switch to postgresql / mysql
-  // by changing the provider + DATABASE_URL in .env.
-  provider = "sqlite"
-  url      = env("DATABASE_URL")
-}
+// Raw drizzle builders, re-exported so the schema reads like drizzle.
+export { text, integer, real, blob };
+
+// Casing factory: column keys map to snake_case SQL names.
+export const table = sqliteTableCreator((name) => name, 'snake_case');
+
+export const pk = () => integer().primaryKey({ autoIncrement: true });
+export const uuidPk = () => text().primaryKey().$defaultFn(() => crypto.randomUUID());
+export const uuid = () => text();
+export const bool = () => integer({ mode: 'boolean' });
+export const timestamp = () => integer({ mode: 'timestamp_ms' });
+export const createdAt = () => timestamp().notNull().defaultNow();
+export const updatedAt = () => timestamp().notNull().defaultNow().$onUpdate(() => new Date());
+
+// Anonymous-style index helper (rc.3 requires a name; this derives a
+// table-qualified one, matching drizzle-kit's own convention).
+export const index = (...cols: SQLiteColumn[]) =>
+  _index(getTableName((cols[0] as unknown as { table: Table }).table) + '_' + cols.map((c) => c.name).join('_') + '_idx').on(...(cols as [SQLiteColumn, ...SQLiteColumn[]]));
+`;
+
+  const columnsPg = `import { pgTableCreator, serial, uuid as pgUuid, integer, text, real, boolean, timestamp as pgTimestamp, index as _index } from 'drizzle-orm/pg-core';
+import type { PgColumn } from 'drizzle-orm/pg-core';
+import { getTableName, type Table } from 'drizzle-orm';
+
+export { text, integer, real };
+
+export const table = pgTableCreator((name) => name, 'snake_case');
+
+export const pk = () => serial().primaryKey();
+export const uuidPk = () => pgUuid().primaryKey().defaultRandom();
+export const uuid = () => pgUuid();
+export const bool = () => boolean();
+export const timestamp = () => pgTimestamp({ withTimezone: true });
+export const createdAt = () => timestamp().notNull().defaultNow();
+export const updatedAt = () => timestamp().notNull().defaultNow().$onUpdate(() => new Date());
+
+export const index = (...cols: PgColumn[]) =>
+  _index(getTableName((cols[0] as unknown as { table: Table }).table) + '_' + cols.map((c) => c.name).join('_') + '_idx').on(...(cols as [PgColumn, ...PgColumn[]]));
+`;
+
+  await writeFile(join(appDir, 'db', 'columns.server.ts'), dialect === 'postgres' ? columnsPg : columnsSqlite);
+
+  // Example schema (dialect-agnostic). Replace the User model with your own.
+  await writeFile(join(appDir, 'db', 'schema.server.ts'), `import { defineRelations } from 'drizzle-orm';
+import { table, pk, text, createdAt } from './columns.server.ts';
 
 // Example model. Feel free to delete or extend.
-model User {
-  id        Int      @id @default(autoincrement())
-  email     String   @unique
-  name      String?
-  createdAt DateTime @default(now())
-}
+export const users = table('users', {
+  id: pk(),
+  email: text().notNull().unique(),
+  name: text(),
+  createdAt: createdAt(),
+});
+
+// Relations live here (one defineRelations for the whole schema). Empty
+// for now; add per-model relations as your schema grows.
+export const relations = defineRelations({ users }, () => ({}));
+
+// Derived types, never hand-written.
+export type User = typeof users.$inferSelect;
 `);
 
-  await writeFile(join(appDir, 'lib', 'prisma.server.ts'), `/**
- * Prisma client singleton. The \`globalThis\` trick keeps a single
- * instance across dev-server module reloads, so we don't open a new
- * DB connection on every file change.
- */
-import { PrismaClient } from '@prisma/client';
+  const connSqlite = `import { isAbsolute, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as schema from './schema.server.ts';
+
+// The only file that opens the driver. Runtime-neutral: native bun:sqlite on
+// Bun, better-sqlite3 on Node. Cached on globalThis across dev reloads.
+// A relative SQLite path resolves against the app root (the parent of db/), not
+// process.cwd(), so the connection works under \`webjs dev\` AND when the app is
+// embedded via createRequestHandler from a different working directory.
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const raw = process.env.DATABASE_URL?.replace(/^file:/, '') ?? 'db/dev.db';
+const url = raw === ':memory:' || isAbsolute(raw) ? raw : resolve(appRoot, raw);
+const g = globalThis as unknown as { __webjs_db?: unknown };
+
+async function open() {
+  if ((globalThis as { Bun?: unknown }).Bun) {
+    const { Database } = await import('bun:sqlite');
+    const { drizzle } = await import('drizzle-orm/bun-sqlite');
+    return drizzle({ client: new Database(url), relations: schema.relations });
+  }
+  const { default: Database } = await import('better-sqlite3');
+  const { drizzle } = await import('drizzle-orm/better-sqlite3');
+  return drizzle({ client: new Database(url), relations: schema.relations });
+}
+
+export const db = (g.__webjs_db ??= await open()) as Awaited<ReturnType<typeof open>>;
+`;
 
-const g = globalThis as unknown as { __prisma?: PrismaClient };
+  const connPg = `import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import * as schema from './schema.server.ts';
 
-export const prisma = g.__prisma ?? new PrismaClient();
-if (process.env.NODE_ENV !== 'production') g.__prisma = prisma;
+// The only file that opens the driver. Cached on globalThis across dev reloads.
+const g = globalThis as unknown as { __webjs_db?: unknown };
+function open() {
+  return drizzle({ client: new Pool({ connectionString: process.env.DATABASE_URL }), relations: schema.relations });
+}
+export const db = (g.__webjs_db ??= open()) as ReturnType<typeof open>;
+`;
+
+  await writeFile(join(appDir, 'db', 'connection.server.ts'), dialect === 'postgres' ? connPg : connSqlite);
+
+  // drizzle-kit config (root, must be this exact filename). DB url from env.
+  await writeFile(join(appDir, 'drizzle.config.ts'), dialect === 'postgres'
+    ? `import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './db/schema.server.ts',
+  out: './db/migrations',
+  dbCredentials: { url: process.env.DATABASE_URL! },
+});
+`
+    : `import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './db/schema.server.ts',
+  out: './db/migrations',
+  dbCredentials: { url: process.env.DATABASE_URL?.replace(/^file:/, '') ?? 'db/dev.db' },
+});
 `);
 
-  // Env vars: append DATABASE_URL to the .env.example the template
-  // already copied (if present). The scaffold's root .env.example
-  // lists auth secrets etc.; we just add the DB line idempotently.
+  // Env vars: append DATABASE_URL to the .env.example the template already
+  // copied (if present), idempotently.
+  const dbUrlLine = dialect === 'postgres'
+    ? 'DATABASE_URL=postgres://user:password@localhost:5432/' + name.replace(/[^a-z0-9_]/gi, '_')
+    : 'DATABASE_URL=file:./db/dev.db';
   const envExample = join(appDir, '.env.example');
   if (existsSync(envExample)) {
-    const cur = await readFile(envExample, 'utf8');
-    if (!cur.includes('DATABASE_URL')) {
-      await writeFile(envExample, cur.replace(/\n?$/, '\n') + '\nDATABASE_URL=file:./prisma/dev.db\n');
+    let cur = await readFile(envExample, 'utf8');
+    // Replace any existing DATABASE_URL line so it is dialect-correct; else append.
+    if (/^DATABASE_URL=.*$/m.test(cur)) {
+      cur = cur.replace(/^DATABASE_URL=.*$/m, dbUrlLine);
+    } else {
+      cur = cur.replace(/\n?$/, '\n') + '\n' + dbUrlLine + '\n';
     }
+    await writeFile(envExample, cur);
   } else {
-    await writeFile(envExample, 'DATABASE_URL=file:./prisma/dev.db\n');
+    await writeFile(envExample, dbUrlLine + '\n');
   }
 
-  // .gitignore the generated SQLite file.
-  const gitignore = join(appDir, '.gitignore');
-  const gitignoreExtra = '\n# SQLite dev database\nprisma/dev.db\nprisma/dev.db-journal\n';
-  if (existsSync(gitignore)) {
-    const cur = await readFile(gitignore, 'utf8');
-    if (!cur.includes('prisma/dev.db')) await writeFile(gitignore, cur + gitignoreExtra);
-  } else {
-    await writeFile(gitignore, 'node_modules\n.webjs\n' + gitignoreExtra);
+  // .gitignore the generated SQLite file (sqlite only; postgres has no local file).
+  if (dialect !== 'postgres') {
+    const gitignore = join(appDir, '.gitignore');
+    const gitignoreExtra = '\n# SQLite dev database\ndb/dev.db\ndb/dev.db-journal\ndb/dev.db-*\n';
+    if (existsSync(gitignore)) {
+      const cur = await readFile(gitignore, 'utf8');
+      if (!cur.includes('db/dev.db')) await writeFile(gitignore, cur + gitignoreExtra);
+    } else {
+      await writeFile(gitignore, 'node_modules\n.webjs\n' + gitignoreExtra);
+    }
   }
 
   // --- App files (template-specific) ---
@@ -1019,7 +1158,7 @@ ThemeToggle.register('theme-toggle');
 `);
   } // end if (!isApi)
 
-  // --- SaaS template extras: auth, dashboard, prisma ---
+  // --- SaaS template extras: auth, dashboard, drizzle User model ---
   if (isSaas) {
     const { writeSaasFiles } = await import('./saas-template.js');
     await writeSaasFiles(appDir);
@@ -1056,9 +1195,9 @@ ThemeToggle.register('theme-toggle');
                     dialog,form,field,switch,checkbox}.ts
     components/theme-toggle.ts
     modules/auth/{actions,queries,types.ts}
-    lib/{auth,prisma,password}.server.ts
+    lib/{auth,password}.server.ts
     lib/utils/cn.ts                      ← cn() helper for ui-* components
-    prisma/schema.prisma                 ← User model
+    db/{schema,columns,connection}.server.ts  ← Drizzle (User model)
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
   } else {
@@ -1096,10 +1235,10 @@ For AI agents, read this before editing scaffolded files:
     no-scaffold-placeholder violations (app/page.ts, app/layout.ts).
     That is the signal to replace the example content. Delete each
     marker comment line as you do, and the check goes green.
-  • Use Prisma + SQLite for app data. It's already wired up. Define
-    real models in prisma/schema.prisma and run \`webjs db migrate\`.
-    NEVER store app data in JSON files, in-memory arrays, or
-    localStorage as a substitute for the database.
+  • Use Drizzle + SQLite for app data. It's already wired up. Define
+    real models in db/schema.server.ts, then run \`webjs db generate\`
+    and \`webjs db migrate\`. NEVER store app data in JSON files,
+    in-memory arrays, or localStorage as a substitute for the database.
   • Only three scaffolds exist: full-stack (default), api, saas. Don't
     invent template names. If you need a different kind of app, pick
     the closest scaffold and adapt it.
@@ -1129,11 +1268,12 @@ For AI agents, read this before editing scaffolded files:
   // to "dev server up" in one command. The full-stack and saas
   // templates ship with @webjsdev/ui already initialised; the api
   // template has no UI but may add one later. Saas needs a one-time
-  // prisma migrate before the first run (the example User model wants
-  // its table to exist).
+  // generate + migrate before the first run (the example User model wants
+  // its table to exist). Drizzle splits Prisma's `migrate dev` into
+  // `db:generate` (schema to SQL) then `db:migrate` (apply).
   const installSegment = installed ? '' : `${pm} install && `;
-  const prismaSegment = isSaas ? `npx prisma migrate dev --name init && ` : '';
-  const runCommand = `cd ${name} && ${installSegment}${prismaSegment}${pm} run dev`;
+  const dbSegment = isSaas ? `${pm} run db:generate && ${pm} run db:migrate && ` : '';
+  const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare
   // `webjs` npm name is owned by an unrelated package; `npx webjs
   // <cmd>` would fetch THAT package instead of ours when run outside