@webjsdev/cli 0.10.17 → 0.10.18

package/templates/CONVENTIONS.md

@@ -32,18 +32,18 @@ enforced by `webjs check`; follow them by judgment.
 
 - **Server actions and queries live in `modules/<feature>/actions/` and
   `modules/<feature>/queries/`** (`*.server.{js,ts}`), not loose in the
-  app root. Cross-cutting server infrastructure (the Prisma singleton,
-  session helpers, auth config) lives in `lib/`.
+  app root. The DB connection lives in `db/connection.server.ts`; other
+  cross-cutting server infrastructure (session helpers, auth config) lives in `lib/`.
 - **One exported function per action/query file.** Name the file after
   the function (`create-post.server.ts` exports `createPost`). It keeps
   the action surface greppable.
 - **Every feature has tests.** A `modules/<feature>/` directory should
   have matching test files under `test/<feature>/`. A unit test for
   logic, a browser/e2e test for user-facing behaviour.
-- **Persist data with Prisma + SQLite, never JSON files.** The scaffold
-  wires up `prisma/schema.prisma` and `lib/prisma.server.ts`. A
+- **Persist data with Drizzle + SQLite, never JSON files.** The scaffold
+  wires up `db/schema.server.ts` and `db/connection.server.ts`. A
   `data/todos.json` or `db.json` used as a database resets on reload and
-  cannot scale; define a Prisma model instead.
+  cannot scale; define a Drizzle table instead.
 
 ---
 
@@ -254,40 +254,45 @@ docs". That is the agent's default behavior in a webjs project.
 
 ---
 
-## Data persistence: Prisma + SQLite, never JSON files
+## Data persistence: Drizzle + SQLite, never JSON files
 
 <!-- OVERRIDE -->
 
-Every webjs app uses **Prisma + SQLite** for persistence by default. The
-scaffold ships `prisma/schema.prisma`, `lib/prisma.server.ts` (singleton), the
-`predev` / `prestart` hooks that run `prisma generate` / `prisma migrate
-deploy`, and `npm run db:migrate` / `db:generate` / `db:studio` scripts.
+Every webjs app uses **Drizzle + SQLite** for persistence by default. The
+scaffold ships the `db/` folder (`schema.server.ts`, `columns.server.ts`,
+`connection.server.ts`), the `webjs.start.before` step that runs
+`webjs db migrate` inside `webjs start` (#550), and the
+`npm run db:generate` / `db:migrate` / `db:push` / `db:studio` / `db:seed`
+scripts (which route through `webjs db` to drizzle-kit). Drizzle has no
+codegen, so there is no dev `before` step.
 
 **AI agents: these rules are absolute.**
 
 1. For ANY data the app stores (todos, posts, messages, products,
-   comments, users…), define a Prisma model in `prisma/schema.prisma`
+   comments, users…), define a Drizzle table in `db/schema.server.ts`
    and persist there.
 2. **NEVER** create JSON files under `data/`, `db.json`, `posts.json`,
    `todos.json`, etc. as a fake database. It resets on reload and cannot
    scale; this is a project convention (see the conventions section above).
 3. **NEVER** use module-scope arrays or `Map`s as a "store". They
    reset on every dev-server reload and can't scale beyond one process.
-4. **NEVER** use `localStorage` / `sessionStorage` to persist app data -
+4. **NEVER** use `localStorage` / `sessionStorage` to persist app data,
    it's per-browser and never reaches the server. Use it only for UI
    preferences (theme, sidebar collapsed, etc.).
-5. To add a model: edit `prisma/schema.prisma`, then `npm run db:migrate
-   -- --name <description>`. Access via `import { prisma } from
-   '../../../lib/prisma.server.ts'` **only inside `.server.{js,ts}` files,
-   `route.ts` handlers, or `middleware.ts`**. Never new `PrismaClient()`.
-   Components, pages, and layouts call into the wrapped server query
-   instead; the framework rewrites that import to an RPC stub on the
-   browser side, so prisma source never reaches the client.
-
-To switch to Postgres or MySQL: change `provider` in
-`prisma/schema.prisma` and the `DATABASE_URL` in `.env`. Do this only
-if the user explicitly asks for it. SQLite is the right default for
-dev and small production workloads.
+5. To add a model: edit `db/schema.server.ts`, then `npm run db:generate`
+   and `npm run db:migrate`. Access via `import { db } from
+   '../../../db/connection.server.ts'` (and the tables from
+   `db/schema.server.ts`) **only inside `.server.{js,ts}` files,
+   `route.ts` handlers, or `middleware.ts`**. Components, pages, and
+   layouts call into the wrapped server query instead; the framework
+   rewrites that import to an RPC stub on the browser side, so the DB
+   driver never reaches the client.
+
+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. SQLite is the right default for dev and small
+production workloads.
 
 ---
 
@@ -302,9 +307,9 @@ saas templates) is a **starting point**.
 
 When the user asks the agent to build their actual app:
 
-1. **Replace the example `User` model** in `prisma/schema.prisma` with
-   the real domain models the app needs (e.g. `Todo`, `Post`, `Message`)
-   - unless the app actually has users.
+1. **Replace the example `User` model** in `db/schema.server.ts` with
+   the real domain models the app needs (e.g. `Todo`, `Post`, `Message`),
+   unless the app actually has users.
 2. **Replace `app/page.ts`** with the app's real homepage. Don't ship
    "Hello from …" as the deliverable.
 3. **Delete or replace `components/theme-toggle.ts`** if the app doesn't
@@ -319,10 +324,11 @@ When the user asks the agent to build their actual app:
    dashboard, or board, or a wide layout overflows into an unnecessary
    horizontal scrollbar. Keep the design tokens and theme setup, those
    are infrastructure.
-6. **Keep:** the Prisma setup, the test config, the agent config files
+6. **Keep:** the Drizzle setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
-   `lib/prisma.server.ts`, the directory conventions, the design tokens in
-   `app/layout.ts`. These are the infrastructure, not the example app.
+   `db/connection.server.ts` + `db/columns.server.ts`, the directory
+   conventions, the design tokens in `app/layout.ts`. These are the
+   infrastructure, not the example app.
 
 This is enforced, not just advised. The example `app/page.ts` and
 `app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and
@@ -334,7 +340,7 @@ line. So the delivered app contains only what the user asked for, never
 leftover scaffold code.
 
 The scaffold exists so the agent doesn't reinvent the directory layout,
-the Prisma wiring, the test runner config, or the convention files. It
+the Drizzle wiring, the test runner config, or the convention files. It
 does NOT exist so the agent ships the example homepage.
 
 ---
@@ -385,7 +391,7 @@ modules/
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - Components must call `Class.register('tag')`
-- **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` or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. `lib/` holds both server-only infra (`lib/prisma.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
+- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`better-sqlite3` / `pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
 - **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 
@@ -919,8 +925,11 @@ route imports and calls it.
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
+import { db } from '../../../db/connection.server.ts';
+import { posts } from '../../../db/schema.server.ts';
 export async function createPost({ title, body }) {
-  return prisma.post.create({ data: { title, body } });
+  const [post] = await db.insert(posts).values({ title, body }).returning();
+  return post;
 }
 ```
 
@@ -1030,7 +1039,8 @@ Where the data lives, where to read it:
 ```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';
 import type { ActionResult } from '../types.ts';
 
 export async function createPost(input: {
@@ -1148,7 +1158,7 @@ Create new projects with `webjs create`:
 ```sh
 webjs create <name>                  # full-stack (default)
 webjs create <name> --template api   # backend-only API
-webjs create <name> --template saas  # auth + dashboard + Prisma User model
+webjs create <name> --template saas  # auth + dashboard + Drizzle User model
 ```
 
 **Route-wrapping pattern (especially for `--template api` apps):**

package/templates/Dockerfile

@@ -21,8 +21,9 @@
 # framework AGENTS.md "Secure response headers" section.
 FROM node:24-alpine
 
-# openssl + ca-certificates are required by Prisma's query engine at runtime.
-RUN apk add --no-cache openssl ca-certificates
+# ca-certificates for outbound TLS (e.g. a managed Postgres). better-sqlite3
+# is a prebuilt native module, so no build toolchain is needed here.
+RUN apk add --no-cache ca-certificates
 
 WORKDIR /app
 
@@ -35,9 +36,9 @@ RUN npm install --no-audit --no-fund
 # App source. node_modules and local state are excluded via .dockerignore.
 COPY . .
 
-# Generate the Prisma client at build time (every scaffold ships a
-# prisma/schema.prisma). If you remove Prisma from the app, delete this line.
-RUN npx prisma generate
+# Drizzle has no client-codegen step, so there is nothing to build here. The
+# database is migrated at boot via `webjs start` (the `webjs.start.before`
+# step runs `webjs db migrate`). See the CMD note below.
 
 ENV NODE_ENV=production
 # webjs start reads $PORT (default 8080). compose / uncloud / Railway set it.
@@ -55,6 +56,8 @@ EXPOSE 8080
 HEALTHCHECK --interval=15s --timeout=3s --start-period=40s --retries=5 \
   CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/__webjs/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
 
-# `npm start` runs `prestart: prisma migrate deploy` (idempotent, a no-op when
-# there are no migrations yet) and then `webjs start`, which serves on $PORT.
+# `npm start` is a thin alias for `webjs start` (#550). `webjs start` runs the
+# `webjs.start.before` step (`webjs db migrate`, idempotent / a no-op with no
+# pending migrations) IN-PROCESS, then serves on $PORT. `CMD ["webjs", "start"]`
+# is now equivalent: the migrate no longer depends on an npm `prestart` hook.
 CMD ["npm", "start"]

package/templates/compose.yaml

@@ -12,9 +12,9 @@ services:
       - "8080:8080"
     environment:
       PORT: 8080
-      # SQLite on a volume for local dev. For production, point DATABASE_URL at
-      # your managed Postgres and switch prisma/schema.prisma's provider to
-      # "postgresql".
+      # SQLite on a volume for local dev. For production, scaffold with
+      # --db postgres (or swap db/columns.server.ts + db/connection.server.ts
+      # for the pg variant) and point DATABASE_URL at your managed Postgres.
       DATABASE_URL: file:/data/dev.db
       # Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
       AUTH_SECRET: ${AUTH_SECRET:-change-me-please-at-least-32-characters!}

package/lib/prisma-preflight.js

@@ -1,168 +0,0 @@
-/**
- * Prisma-client preflight for `webjs dev` (#452).
- *
- * The scaffold's `dev` npm script is `webjs dev`, and `npm run dev` runs the
- * `predev` hook (`prisma generate`) FIRST. Invoking the `webjs dev` binary
- * directly (easy to do, and tempting for an AI/CLI) skips `predev`, so the dev
- * server boots against an ungenerated `@prisma/client` and crashes with a raw
- * "did not initialize yet" error and no hint that the canonical command is
- * `npm run dev`. This turns that crash into a one-line, actionable message.
- *
- * Scope is deliberately narrow: it only fires for an app that actually uses
- * Prisma (a `prisma/schema.prisma` OR an `@prisma/client` dependency), and it
- * only HINTS. It never auto-runs an arbitrary `predev` script and never shells
- * out to `prisma generate` on its own, keeping the no-build promise intact.
- *
- * Detection (verified against a real Prisma 6 install): the GENERATED
- * `.prisma/client` target is resolved through standard Node resolution from the
- * app (so a hoisted monorepo, where the client lives at a PARENT `node_modules`,
- * resolves correctly), then read. An ABSENT target, or a present-but-stub target
- * (the ungenerated client whose `PrismaClient` constructor throws the init
- * error), is "ungenerated". A real generated target older than the schema is
- * "stale". We do NOT grep the static `@prisma/client` re-export shim: it is
- * present in both states and never carries the init-error string itself.
- */
-import { existsSync, statSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { createRequire } from 'node:module';
-
-/**
- * Does this app use Prisma? True if a schema is checked in OR `@prisma/client`
- * is a declared dependency. Either alone is enough; a non-Prisma app has
- * neither and gets no warning.
- *
- * @param {string} cwd
- * @returns {boolean}
- */
-export function usesPrisma(cwd) {
-  if (existsSync(join(cwd, 'prisma', 'schema.prisma'))) return true;
-  try {
-    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
-    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-    return Boolean(deps && deps['@prisma/client']);
-  } catch {
-    return false;
-  }
-}
-
-// Marker the ungenerated `prisma-client-js` stub embeds in its generated target
-// (`node_modules/.prisma/client/index.js`). Verified against a real Prisma 6
-// install: after `npm i @prisma/client` but before `prisma generate`, the
-// generated `.prisma/client` entry IS present but its `PrismaClient` constructor
-// throws `@prisma/client did not initialize yet. Please run "prisma generate"`.
-// A real `prisma generate` replaces that stub with the generated client, which
-// does NOT contain this string. So the marker, read from the GENERATED target
-// (not the static `@prisma/client` shim), is the reliable ungenerated signal.
-const UNGENERATED_MARKER = 'did not initialize yet';
-
-/**
- * Resolve the GENERATED Prisma client entry (`.prisma/client/index.js`) for an
- * app, following standard Node resolution so a hoisted monorepo layout (the
- * generated client at a PARENT `node_modules`, the app under `apps/<x>`) still
- * resolves. Returns a discriminated result so the caller can tell the three
- * cases apart:
- *   - `{ kind: 'unresolved' }`        - `@prisma/client` itself is not resolvable.
- *   - `{ kind: 'no-target' }`         - the package resolves but `.prisma/client`
- *                                       does not (a custom `output`, ambiguous).
- *   - `{ kind: 'target', path }`      - the generated target resolves.
- *
- * @param {string} cwd
- * @returns {{ kind: 'unresolved' } | { kind: 'no-target' } | { kind: 'target', path: string }}
- */
-function resolveGeneratedClient(cwd) {
-  let clientDir;
-  try {
-    // Resolve @prisma/client AS THE APP would (hoisting-aware), then locate its
-    // package dir. The shim itself loads `.prisma/client/default` relative to
-    // here, so resolving from this dir follows the same (possibly hoisted) path.
-    const appRequire = createRequire(join(cwd, 'noop.js'));
-    clientDir = dirname(appRequire.resolve('@prisma/client'));
-  } catch {
-    return { kind: 'unresolved' };
-  }
-  const shimRequire = createRequire(join(clientDir, 'noop.js'));
-  for (const entry of ['.prisma/client/index.js', '.prisma/client/default.js']) {
-    try {
-      return { kind: 'target', path: shimRequire.resolve(entry) };
-    } catch { /* try the next entry */ }
-  }
-  return { kind: 'no-target' };
-}
-
-/**
- * Inspect the generated Prisma client state for a Prisma app.
- *
- * Returns one of:
- *   - `{ status: 'ok' }`         - client generated and not older than the schema.
- *   - `{ status: 'missing' }`    - schema/dep present but no generated client.
- *   - `{ status: 'stale' }`      - client exists but the schema is newer than it.
- *
- * Detection resolves the GENERATED `.prisma/client` target through standard Node
- * resolution (so hoisted monorepos are handled) and reads it: an absent target,
- * or a present-but-stub target (the ungenerated `PrismaClient` that throws on
- * construction), is `missing`. A real generated client that is older than the
- * schema is `stale`. A custom-`output` generator whose target Node cannot
- * resolve falls back to `ok` rather than nag a working app (false positives are
- * worse than a missed hint here).
- *
- * @param {string} cwd
- * @returns {{ status: 'ok' | 'missing' | 'stale' }}
- */
-export function prismaClientState(cwd) {
-  const resolved = resolveGeneratedClient(cwd);
-
-  // @prisma/client not resolvable: the app declared the dep (usesPrisma gated
-  // us here) but it is not installed/generated. That is the boot-crash case.
-  if (resolved.kind === 'unresolved') return { status: 'missing' };
-
-  // The package resolves but the default `.prisma/client` target does not: a
-  // custom `output` whose location we cannot cheaply verify. Fall back to `ok`
-  // rather than nag a working app (false positives are worse than a missed hint).
-  if (resolved.kind === 'no-target') return { status: 'ok' };
-
-  const generatedIndex = resolved.path;
-
-  // The generated target exists. Is it still the ungenerated stub (its
-  // PrismaClient constructor throws the init error)?
-  try {
-    const body = readFileSync(generatedIndex, 'utf8');
-    if (body.includes(UNGENERATED_MARKER)) return { status: 'missing' };
-  } catch { /* unreadable: fall through to the stale check, then ok */ }
-
-  // Generated for real. Is it older than the schema (a stale client)?
-  const schema = join(cwd, 'prisma', 'schema.prisma');
-  try {
-    if (existsSync(schema)) {
-      const schemaMtime = statSync(schema).mtimeMs;
-      const clientMtime = statSync(generatedIndex).mtimeMs;
-      if (schemaMtime > clientMtime) return { status: 'stale' };
-    }
-  } catch { /* if we can't stat, treat as ok */ }
-
-  return { status: 'ok' };
-}
-
-/**
- * Build the actionable hint for an ungenerated/stale client, or `null` when the
- * app is fine or does not use Prisma. The caller prints it (a warning, not a
- * hard exit) before booting the dev server.
- *
- * @param {string} cwd
- * @returns {string | null}
- */
-export function prismaDevHint(cwd) {
-  if (!usesPrisma(cwd)) return null;
-  const { status } = prismaClientState(cwd);
-  if (status === 'ok') return null;
-
-  const reason =
-    status === 'stale'
-      ? 'Your Prisma client looks stale (the schema changed since it was generated).'
-      : 'Your Prisma client is not generated yet.';
-  return (
-    `webjs: ${reason}\n` +
-    `  The dev server will crash on an ungenerated client. Fix it with either:\n` +
-    `    npm run dev          # canonical: runs \`prisma generate\` (predev) first\n` +
-    `    webjs db generate    # just regenerate the client, then re-run\n`
-  );
-}