@webjsdev/cli 0.10.17 → 0.10.18

package/lib/run-tasks.js

@@ -0,0 +1,100 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { delimiter, dirname, join } from 'node:path';
+
+/**
+ * Build a PATH the way `npm run` does: prepend every ANCESTOR
+ * `node_modules/.bin` (the app's, then up to the repo root for a hoisted
+ * monorepo) so a `before` / `parallel` command naming a LOCAL-only binary
+ * (`drizzle-kit`, `tailwindcss`) resolves under a bare `webjs dev` / `start`, exactly
+ * as it does under `npm run dev`. Without this a bare `webjs dev` exits 127 on
+ * the first such step and aborts the boot, defeating the whole #550 point.
+ *
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function envWithLocalBin(cwd, env = process.env) {
+  const bins = [];
+  let dir = cwd;
+  // Walk up to the filesystem root, collecting each node_modules/.bin.
+  for (;;) {
+    bins.push(join(dir, 'node_modules', '.bin'));
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { ...env, PATH: [...bins, env.PATH || ''].join(delimiter) };
+}
+
+/**
+ * Run the configured `before` steps (#550) sequentially to completion. Returns
+ * the FIRST failure so the caller can abort the boot, or `{ ok: true }`. Pure of
+ * `process.exit` and `console` (the bin owns the exit code + logging via the
+ * `onStep` hook) so the orchestration is deterministically unit-testable, with
+ * `spawn` injectable for tests.
+ *
+ * @param {string[]} steps
+ * @param {string} cwd
+ * @param {{ spawn?: typeof nodeSpawn, onStep?: (step: string) => void }} [opts]
+ * @returns {Promise<{ ok: true } | { ok: false, step: string, code: number }>}
+ */
+export async function runBeforeSteps(steps, cwd, opts = {}) {
+  const spawn = opts.spawn || nodeSpawn;
+  const env = envWithLocalBin(cwd);
+  for (const step of steps) {
+    if (opts.onStep) opts.onStep(step);
+    const code = await new Promise((res) => {
+      const c = spawn(step, { shell: true, stdio: 'inherit', cwd, env });
+      c.on('exit', (code) => res(code ?? 0));
+      c.on('error', () => res(1));
+    });
+    if (code !== 0) return { ok: false, step, code };
+  }
+  return { ok: true };
+}
+
+/**
+ * Spawn the configured dev `parallel` tasks (#550) as long-lived children and
+ * return a killer that tears them ALL down (idempotent), so a watcher cannot
+ * leak past the dev server. `spawn` is injectable for tests.
+ *
+ * @param {string[]} commands
+ * @param {string} cwd
+ * @param {{ spawn?: typeof nodeSpawn, onStart?: (cmd: string) => void }} [opts]
+ * @returns {() => void}
+ */
+export function startParallelTasks(commands, cwd, opts = {}) {
+  const spawn = opts.spawn || nodeSpawn;
+  const env = envWithLocalBin(cwd);
+  const children = commands.map((cmd) => {
+    if (opts.onStart) opts.onStart(cmd);
+    // `detached: true` puts the child in its OWN process group, so the killer
+    // can take down the whole tree (the `sh -c` wrapper AND the watcher it
+    // spawns, e.g. tailwindcss) rather than just the shell, which would leak the
+    // watcher as an orphan.
+    return spawn(cmd, { shell: true, stdio: 'inherit', cwd, env, detached: true });
+  });
+  let killed = false;
+  return () => {
+    if (killed) return;
+    killed = true;
+    for (const c of children) killChildTree(c);
+  };
+}
+
+/**
+ * Tear down a shell-spawned child's whole process GROUP. A `sh -c '<watcher>'`
+ * child run with `detached: true` is a group leader, so a NEGATIVE pid signals
+ * the group (the shell + the watcher). Falls back to a direct `kill()` when
+ * there is no numeric pid (a fake child in a test) or the group kill is
+ * unsupported (a non-POSIX runtime), so the killer never throws.
+ *
+ * @param {import('node:child_process').ChildProcess} child
+ */
+function killChildTree(child) {
+  try {
+    if (typeof child.pid === 'number') process.kill(-child.pid, 'SIGTERM');
+    else child.kill();
+  } catch {
+    try { child.kill(); } catch {}
+  }
+}

package/lib/saas-template.js

@@ -50,16 +50,10 @@ export async function writeSaasFiles(appDir) {
   // the saas auth pages use raw <form> + label/input class helpers instead.
   await copyUiComponents(appDir, ['dialog', 'switch', 'checkbox']);
 
-  // lib/prisma.server.ts
+  // The db/ layer (columns/connection) is written by the full-stack scaffold
+  // already; this template overwrites db/schema.server.ts below to add the
+  // User.passwordHash column auth needs.
   await mkdir(join(appDir, 'lib'), { recursive: true });
-  await writeFile(join(appDir, 'lib', 'prisma.server.ts'), [
-    "import { PrismaClient } from '@prisma/client';",
-    "",
-    "const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };",
-    "export const prisma = globalForPrisma.prisma || new PrismaClient();",
-    "if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;",
-    "",
-  ].join('\n'));
 
   // lib/password.server.ts
   await writeFile(join(appDir, 'lib', 'password.server.ts'), [
@@ -85,14 +79,14 @@ export async function writeSaasFiles(appDir) {
   // lib/auth.server.ts
   await writeFile(join(appDir, 'lib', 'auth.server.ts'), [
     "import { createAuth, Credentials } from '@webjsdev/server';",
-    "import { prisma } from './prisma.server.ts';",
+    "import { db } from '../db/connection.server.ts';",
     "import { compare } from './password.server.ts';",
     "",
     "export const { auth, signIn, signOut, handlers } = createAuth({",
     "  providers: [",
     "    Credentials({",
     "      async authorize(credentials: { email: string; password: string }) {",
-    "        const user = await prisma.user.findUnique({ where: { email: credentials.email } });",
+    "        const user = await db.query.users.findFirst({ where: { email: credentials.email } });",
     "        if (!user || !await compare(credentials.password, user.passwordHash)) return null;",
     "        return { id: String(user.id), name: user.name, email: user.email };",
     "      },",
@@ -103,26 +97,24 @@ export async function writeSaasFiles(appDir) {
     "",
   ].join('\n'));
 
-  // prisma/schema.prisma
-  await mkdir(join(appDir, 'prisma'), { recursive: true });
-  await writeFile(join(appDir, 'prisma', 'schema.prisma'), [
-    'datasource db {',
-    '  provider = "sqlite"',
-    '  url      = env("DATABASE_URL")',
-    '}',
-    '',
-    'generator client {',
-    '  provider = "prisma-client-js"',
-    '}',
-    '',
-    'model User {',
-    '  id           Int      @id @default(autoincrement())',
-    '  email        String   @unique',
-    '  name         String?',
-    '  passwordHash String',
-    '  createdAt    DateTime @default(now())',
-    '}',
-    '',
+  // db/schema.server.ts: overwrite the full-stack scaffold's example User to
+  // add passwordHash (the column auth needs). Drizzle, dialect-agnostic.
+  await writeFile(join(appDir, 'db', 'schema.server.ts'), [
+    "import { defineRelations } from 'drizzle-orm';",
+    "import { table, pk, text, createdAt } from './columns.server.ts';",
+    "",
+    "export const users = table('users', {",
+    "  id: pk(),",
+    "  email: text().notNull().unique(),",
+    "  name: text(),",
+    "  passwordHash: text().notNull(),",
+    "  createdAt: createdAt(),",
+    "});",
+    "",
+    "export const relations = defineRelations({ users }, () => ({}));",
+    "",
+    "export type User = typeof users.$inferSelect;",
+    "",
   ].join('\n'));
 
   // modules/auth/actions/signup.server.ts
@@ -132,15 +124,14 @@ export async function writeSaasFiles(appDir) {
   await writeFile(join(appDir, 'modules', 'auth', 'actions', 'signup.server.ts'), [
     "'use server';",
     "",
-    "import { prisma } from '../../../lib/prisma.server.ts';",
+    "import { db } from '../../../db/connection.server.ts';",
+    "import { users } from '../../../db/schema.server.ts';",
     "import { hash } from '../../../lib/password.server.ts';",
     "",
     "export async function signup(input: { name: string; email: string; password: string }) {",
-    "  const exists = await prisma.user.findUnique({ where: { email: input.email } });",
+    "  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });",
     "  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };",
-    "  const user = await prisma.user.create({",
-    "    data: { name: input.name, email: input.email, passwordHash: await hash(input.password) },",
-    "  });",
+    "  const [user] = await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) }).returning();",
     "  return { success: true as const, data: { id: user.id, name: user.name, email: user.email } };",
     "}",
     "",
@@ -183,11 +174,10 @@ export async function writeSaasFiles(appDir) {
   //   - The protected-route gate (unauthenticated /dashboard -> 302 /login) runs
   //     ALWAYS once the app modules import: auth() only reads a cookie, no DB
   //     query. This is the headline security assertion and it is REAL.
-  //   - The signup -> login -> protected-route flow writes + reads a user, so it
-  //     needs Prisma generated AND migrated (`npm run db:generate` +
-  //     `npm run db:migrate`). When the Prisma client is not yet generated the
-  //     app modules can't import at all, so the whole suite skips with a clear
-  //     message instead of crashing. After you set up the DB it runs for real.
+  //   The signup, login, and protected-route flow writes + reads a user, so it
+  //   needs the DB migrated (`npm run db:generate` then `npm run db:migrate`).
+  //   Until the users table exists those flows error, so the suite skips with a
+  //   clear message instead of crashing. After DB setup it runs for real.
   await mkdir(join(appDir, 'test', 'auth'), { recursive: true });
   await writeFile(join(appDir, 'test', 'auth', 'auth.test.ts'), [
     "import { test } from 'node:test';",
@@ -200,20 +190,20 @@ export async function writeSaasFiles(appDir) {
     "",
     "const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');",
     "",
-    "// The auth pages + dashboard middleware import lib/prisma.server.ts, which",
-    "// imports @prisma/client. Until `npm run db:generate` (prisma generate) has",
-    "// run, that import is missing, so a request hitting those modules 500s. We",
-    "// detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a",
-    "// clear message rather than reporting a misleading failure. After you run",
+    "// The auth pages + dashboard middleware query the users table via Drizzle.",
+    "// Until `npm run db:generate` + `npm run db:migrate` have created it, a",
+    "// request hitting those modules 500s. We detect that at the RESPONSE level",
+    "// (a 5xx on the dashboard) and SKIP with a clear message rather than report",
+    "// a misleading failure. After you run",
     "//   npm install && npm run db:generate && npm run db:migrate",
     "// every assertion below runs for real.",
     "process.env.DATABASE_URL ||= 'file:./dev.db';",
     "process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';",
     "",
     "function makeHandler() {",
-    "  // createRequestHandler builds lazily, so it succeeds even before prisma is",
-    "  // generated; the missing dependency only surfaces when a request reaches",
-    "  // the prisma-importing module. That is why readiness is probed per-response.",
+    "  // createRequestHandler builds lazily, so it succeeds even before the DB",
+    "  // is migrated; the missing table only surfaces when a request reaches a",
+    "  // module that queries it. That is why readiness is probed per-response.",
     "  return createRequestHandler({ appDir, dev: true });",
     "}",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.17",
+  "version": "0.10.18",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -7,10 +7,10 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
-- **Use Prisma + SQLite for data, never JSON files.** It is already wired up
-  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For
+- **Use Drizzle + SQLite for data, never JSON files.** It is already wired up
+  (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate` + `npm run db:migrate`). For
   ANY data the app stores (todos, posts, messages, products, comments), define
-  a Prisma model. NEVER create `data/*.json`, `db.json`, or any JSON file as a
+  a Drizzle table. NEVER create `data/*.json`, `db.json`, or any JSON file as a
   fake database. NEVER use module-scope arrays / Maps as a substitute. NEVER
   use localStorage for app data. These are project conventions in
   CONVENTIONS.md (a JSON file used as a database resets on reload and
@@ -131,12 +131,12 @@ self-review loop.
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
 - One function per server action file (`*.server.ts`).
-- Server-only code (`@prisma/client`, `node:*`, anything that needs Node APIs)
+- Server-only code (a DB driver like `better-sqlite3`/`pg`, `node:*`, anything that needs Node APIs)
   goes only in `.server.{js,ts}` files, `route.ts` handlers, or
   `middleware.ts`. Never in pages, layouts, or components. Wrap the access in
   a `.server.{js,ts}` file; the framework rewrites that import into an RPC
   stub for the browser. `lib/` holds both server-only infra
-  (`lib/prisma.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
+  (the DB in `db/*.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
   `cn`); follow the same rule per file.
 - Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat`
   ship. Use plain template-literal expressions

package/templates/.env.example

@@ -23,5 +23,5 @@ AUTH_SECRET=
 # REDIS_URL=redis://localhost:6379
 
 # ── Database ────────────────────────────────────────────────────────
-# Used by Prisma. SQLite for dev, PostgreSQL/MySQL for production.
-DATABASE_URL=file:./dev.db
+# Used by Drizzle. SQLite for dev, PostgreSQL for production (--db postgres).
+DATABASE_URL=file:./db/dev.db

package/templates/.github/copilot-instructions.md

@@ -7,10 +7,10 @@ the full hosted docs are at **https://docs.webjs.com**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
-- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
-  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
+- **Use Drizzle + SQLite for data, never JSON files.** It's already wired up
+  (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate` + `npm run db:migrate`). For ANY
   data the app stores (todos, posts, messages, products, comments…),
-  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
+  define a Drizzle table. NEVER create `data/*.json`, `db.json`, or any
   JSON file as a fake database. NEVER use module-scope arrays / Maps as
   a substitute. NEVER use localStorage for app data. It resets on reload and cannot scale. This is a project convention
   (CONVENTIONS.md).
@@ -104,7 +104,7 @@ each change must include.
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
-- Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Server-only code (a DB driver like better-sqlite3/pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
 - Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'

package/templates/.github/workflows/ci.yml

@@ -45,9 +45,8 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - run: npx prisma generate
-      - name: Apply migrations to the test database
-        run: npx prisma migrate deploy
+      - name: Set up the database (generate + apply migrations)
+        run: npm run db:generate && npm run db:migrate
         env:
           DATABASE_URL: file:./ci.db
       # --server keeps this job to node:test (the browser layer is its own
@@ -66,7 +65,6 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - run: npx prisma generate
       - name: Install Playwright Chromium
         run: npx playwright install --with-deps chromium
       - run: npm run test:browser
@@ -81,9 +79,8 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - run: npx prisma generate
-      - name: Apply migrations to the test database
-        run: npx prisma migrate deploy
+      - name: Set up the database (generate + apply migrations)
+        run: npm run db:generate && npm run db:migrate
         env:
           DATABASE_URL: file:./ci.db
       # The scaffold's e2e test (test/hello/e2e/) drives a real browser

package/templates/AGENTS.md

@@ -11,7 +11,7 @@ companion and reach for docs.webjs.com whenever you need more detail.
 
 This project was created with `webjs create`. The files you see right
 now (`app/page.ts` printing "Hello from {{APP_NAME}}", the example `User`
-model in `prisma/schema.prisma`, the `theme-toggle` component, the
+model in `db/schema.server.ts`, the `theme-toggle` component, the
 example users module in api/saas templates) are **starting-point
 references, not the final product**. Your job is to replace them with
 the app the user actually asked for. That includes adapting
@@ -30,11 +30,11 @@ user asked for, never leftover scaffold code.
 
 **Non-negotiables for every webjs app:**
 
-1. **Use Prisma + SQLite for persistence.** It's already wired up
-   (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`,
-   `predev` hook running `prisma generate`). For any data the app
-   stores (todos, posts, messages, products, comments, anything),
-   define a Prisma model and persist there.
+1. **Use Drizzle + SQLite for persistence.** It's already wired up
+   (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate`
+   + `npm run db:migrate`). For any data the app stores (todos, posts,
+   messages, products, comments, anything), define a Drizzle table and
+   persist there.
    - **NEVER** store app data in JSON files (`data/todos.json`,
      `db.json`, …). It resets on reload and cannot scale. This is a project convention,
      and the user's prompt explicitly forbids it.
@@ -47,10 +47,10 @@ user asked for, never leftover scaffold code.
    `full-stack` (default), `--template api`, `--template saas`. Don't
    reach for a `--template blog` / `--template todo` / `--template
    ecommerce`. They don't exist and the CLI will reject them.
-3. **First step after scaffolding:** edit `prisma/schema.prisma` to the
+3. **First step after scaffolding:** edit `db/schema.server.ts` to the
    app's real domain models (delete the example `User` model unless the
-   app actually needs users), run `webjs db migrate <name>`, then build
-   pages / actions / queries against those models.
+   app actually needs users), run `webjs db generate` then
+   `webjs db migrate`, then build pages / actions / queries against them.
 
 **Picking the right scaffold from the user's prompt** (you do this BEFORE
 running `webjs create`; if you're reading this you've already scaffolded.
@@ -322,12 +322,15 @@ modules/<feature>/
   utils/*.ts             feature-scoped helpers
   types.ts               feature types
 lib/
-  prisma.ts              PrismaClient singleton (import from here, never `new PrismaClient()`)
-  ...                    other cross-cutting infra (session, auth config, etc.)
-prisma/
-  schema.prisma          Prisma schema, SQLite by default, switch provider for Postgres/MySQL
-  dev.db                 SQLite file (gitignored); run `npm run db:migrate` to create
-  migrations/            generated migration SQL
+  ...                    cross-cutting infra (session, auth config, etc.)
+db/
+  schema.server.ts       Drizzle models + relations (your data layer)
+  columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
+  connection.server.ts   opens the driver, exports the \`db\` singleton (import \`db\` from here)
+  seed.server.ts         optional seed (run via \`webjs db seed\`)
+  dev.db                 SQLite file (gitignored); run \`npm run db:migrate\` to create
+  migrations/            generated migration SQL (committed)
+drizzle.config.ts        drizzle-kit config (root; SQLite by default, --db postgres to switch)
 public/                  static assets, served at /public/*
 test/<feature>/                feature-scoped tests, one folder per concern
   <name>.test.ts                node unit / integration test (node --test)
@@ -359,39 +362,44 @@ Run `webjs types` once (and ensure `tsconfig.json` `include` lists
 startup, so it stays current. Without it, `params` is `Record<string, string>`
 and `navigate()` accepts any string (non-breaking).
 
-## Database (Prisma + SQLite by default)
+## Database (Drizzle + SQLite by default)
 
-Every scaffold includes a Prisma setup pointed at a local SQLite file.
+Every scaffold includes a Drizzle setup pointed at a local SQLite file,
+under a `db/` folder (`schema.server.ts`, `columns.server.ts`,
+`connection.server.ts`). Drizzle has no codegen and no engine binary.
 First-run workflow:
 
 ```sh
 cp .env.example .env          # DATABASE_URL is pre-filled for SQLite
-npm run db:migrate            # creates prisma/dev.db + migration
-npm run dev                   # webjs dev + prisma generate via predev
+npm run db:generate           # schema -> SQL migration (drizzle-kit)
+npm run db:migrate            # apply it (creates db/dev.db)
+npm run dev                   # webjs dev, then serves
 ```
 
-### Always `npm run dev` / `npm start`, never `webjs dev` / `webjs start` directly
+### `npm run dev` / `npm start` and `webjs dev` / `webjs start` behave identically
 
-`webjs dev` and `webjs start` are framework primitives, they only run
-the webjs server. They do **not** run `prisma generate`, do **not** run
-`prisma migrate deploy`, do **not** spawn the Tailwind watcher, do
-**not** run any other per-app process this `package.json` composes.
+`npm run dev` and `npm start` are the documented entrypoints, and they
+are thin aliases for `webjs dev` / `webjs start`. The start orchestration
+(applying migrations, and any parallel watcher like the Tailwind CLI)
+lives in the `webjs` block of `package.json` and runs INSIDE
+`webjs dev` / `webjs start`:
 
-`npm run dev` and `npm start` are the app-level entrypoints. They run
-the webjs server **plus** every other process the app needs, wired
-together via `predev` / `prestart` hooks and (where present)
-`concurrently` for parallel watchers. Skipping the npm wrapper produces
-silent breakage: a stale Prisma client, missing `public/tailwind.css`,
-an unmigrated database in production, etc.
+```jsonc
+"webjs": {
+  "start": { "before": ["webjs db migrate"] }
+}
+```
 
-Same split Rails 7+ uses: `bin/rails server` is the framework
-primitive, `bin/dev` is the orchestrator. webjs uses npm scripts +
-hooks for the same role, because as a no-build framework Tailwind /
-Prisma / etc. cannot be bundler plugins.
+Drizzle has no codegen, so there is no dev `before` step. An app that
+adds the Tailwind CLI puts its `--watch` command under
+`webjs.dev.parallel` and it runs alongside the server, torn down on exit.
+`before` steps run to completion first; a failed `webjs db migrate`
+aborts the boot with a clear message rather than serving a stale schema.
 
-In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
-start`) as the CMD over `node ... webjs.js start ...`. The npm form
-fires `prestart`; the direct binary form skips it.
+In Docker / Railway, `CMD ["npm", "start"]` and `CMD ["webjs", "start"]`
+are equivalent: `webjs start` runs `webjs.start.before` (`webjs db
+migrate`) in-process before serving, so the migrate no longer depends on
+an npm `prestart` hook.
 
 ### Running on Bun instead of Node
 
@@ -407,14 +415,16 @@ bun --bun run dev      # or: bun --bun run start
 On Node the `.ts` type-stripping is the built-in `module.stripTypeScriptTypes`;
 on Bun (which has no built-in) it comes from `amaro` automatically, so the same
 source serves identically. SSR action-result seeding (an internal hydration
-optimization) is off on Bun (it needs `module.registerHooks`), which only means
-an async-render component re-fetches once on hydration, no behavior change.
+optimization) works on both runtimes: Node installs it via `module.registerHooks`,
+Bun via a `Bun.plugin` `onLoad`, so an async-render component does not re-fetch
+on hydration on either runtime.
 
 **Containerized deploy ships with the scaffold.** `Dockerfile`,
 `compose.yaml`, and `.dockerignore` are scaffolded at the app root. The
 Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs
-deps, runs `prisma generate`, and starts via `npm start` so `prestart`
-applies migrations. Run it locally with `docker compose up --build` (the
+deps (no build step, since Drizzle has no codegen), and starts via
+`npm start` (`webjs start` runs `webjs.start.before` = `webjs db migrate`
+before serving). Run it locally with `docker compose up --build` (the
 app comes up on http://localhost:8080 against a SQLite file on a named
 volume). For production, point `DATABASE_URL` at managed Postgres and set
 `AUTH_SECRET`. The `.dockerignore` keeps the `.webjs/vendor/` importmap in
@@ -439,24 +449,28 @@ live DB ping), add an optional `readiness.{js,ts}` at the app root that
 default-exports an async check; `/__webjs/ready` runs it once warm and reports
 503 if it returns `false` or throws.
 
-Scripts:
+Scripts (all wrap `drizzle-kit`):
 
-- `npm run db:migrate`: `prisma migrate dev` (dev-time schema changes + migration + generate)
-- `npm run db:generate`: `prisma generate` (regenerate client only)
-- `npm run db:studio`: `prisma studio` (GUI)
-- `predev` hook auto-runs `prisma generate` before `npm run dev`
-- `prestart` hook runs `prisma migrate deploy` before `npm start` (idempotent in prod)
+- `npm run db:generate`: `webjs db generate` (schema -> SQL migration)
+- `npm run db:migrate`: `webjs db migrate` (apply pending migrations)
+- `npm run db:push`: `webjs db push` (push the schema straight to the dev DB)
+- `npm run db:studio`: `webjs db studio` (visual DB browser)
+- `npm run db:seed`: `webjs db seed` (run `db/seed.server.ts`)
+- `webjs.start.before` runs `webjs db migrate` inside `webjs start` (idempotent; replaces the old `prestart` hook). No dev `before` step (no codegen).
 
-Always import the client from `lib/prisma.server.ts` (never `new PrismaClient()` directly -
-the singleton avoids opening a new connection on every dev-server reload):
+Always import `db` from `db/connection.server.ts` (the globalThis-cached
+singleton avoids opening a new connection on every dev-server reload), and
+the tables from `db/schema.server.ts`:
 
 ```ts
-import { prisma } from '../../../lib/prisma.server.ts';
-const users = await prisma.user.findMany();
+import { db } from '../../../db/connection.server.ts';
+const users = await db.query.users.findMany();
 ```
 
-To switch to Postgres or MySQL: change `provider` in `prisma/schema.prisma`
-and the `DATABASE_URL` in `.env`.
+To switch to Postgres: scaffold with `--db postgres`, or swap
+`db/columns.server.ts` + `db/connection.server.ts` for the Postgres
+variants and point `DATABASE_URL` at Postgres. The schema, queries, and
+actions are unchanged.
 
 ## NPM packages (vendor pipeline)
 
@@ -521,9 +535,9 @@ committed manifest, optional `--download` for full offline capability,
 and a `--from` knob to swap the resolver CDN if jspm.io has an
 incident.
 
-**Don't auto-run `webjs vendor pin` in `predev` / `prestart`.** Auto-pin
-would silently churn the committed importmap.json as jspm.io resolves
-URLs or transitive deps drift. Pin is a deliberate developer action,
+**Don't auto-run `webjs vendor pin` in a `webjs.dev.before` / `webjs.start.before`
+step.** Auto-pin would silently churn the committed importmap.json as jspm.io
+resolves URLs or transitive deps drift. Pin is a deliberate developer action,
 like `npm install` itself.
 
 **Do NOT modify the `.webjs/` lines in `.gitignore` / `.dockerignore`.**
@@ -740,11 +754,12 @@ legitimately use `static styles = css\`\`` for scoped CSS.
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { db } from '../../../db/connection.server.ts';
+import { posts } from '../../../db/schema.server.ts';
 
 export async function createPost(input: { title: string; body: string }) {
   if (!input.title) return { success: false, error: 'title required', status: 400 };
-  const post = await prisma.post.create({ data: input });
+  const [post] = await db.insert(posts).values(input).returning();
   return { success: true, data: post };
 }
 ```
@@ -1117,13 +1132,14 @@ composition, so a nested shell ends up dropped by the HTML parser.
 1. Custom element tags must contain a hyphen. Pass the tag to `.register('tag-name')` at the bottom of the file. The tag is not a static field.
 2. **Server-only code goes in `.server.{js,ts}` files, `route.ts`
    handlers, or `middleware.ts`. Never in pages, layouts, or
-   components.** Direct imports of `@prisma/client`, `node:*`, or any
-   server-only dependency from a page, layout, loading.ts, error.ts,
-   not-found.ts, or component will crash the browser at module load.
+   components.** Direct imports of a DB driver (`better-sqlite3` / `pg`),
+   `node:*`, or any server-only dependency from a page, layout, loading.ts,
+   error.ts, not-found.ts, or component will crash the browser at module load.
    Wrap the access in a `.server.{js,ts}` file; the framework
-   rewrites that import into an RPC stub for the browser. `lib/`
-   holds both server-only infra (`lib/prisma.server.ts`, `lib/session.server.ts`)
-   and browser-safe utilities (`lib/utils/cn.ts` with `cn`, design-
+   rewrites that import into an RPC stub for the browser. Server-only
+   infra lives in `db/*.server.ts` (the DB) and `lib/*.server.ts`
+   (`lib/session.server.ts`); browser-safe utilities live in
+   `lib/utils/cn.ts` with `cn`, design-
    system helpers). Server-only `lib/*` files must only be imported
    from `.server.ts`/`route.ts`/`middleware.ts`; browser-safe `lib/*`
    files (like `lib/utils/cn.ts`) can be imported anywhere.