@webjsdev/cli 0.10.17 → 0.10.19

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.
@@ -202,10 +202,10 @@ Pure functions that return Tailwind class strings. You apply them to
 import {
   cardClass, cardHeaderClass, cardTitleClass,
   cardContentClass, cardFooterClass,
-} from '../../components/ui/card.ts';
-import { inputClass } from '../../components/ui/input.ts';
-import { labelClass } from '../../components/ui/label.ts';
-import { buttonClass } from '../../components/ui/button.ts';
+} from '#components/ui/card.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { labelClass } from '#components/ui/label.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 return html`
   <div class=${cardClass()}>
@@ -237,13 +237,13 @@ elements. Import them once (typically in `app/layout.ts`) and use
 
 ```ts
 // app/layout.ts (registers the custom elements for every page)
-import '../components/ui/dialog.ts';
-import '../components/ui/tabs.ts';
+import '#components/ui/dialog.ts';
+import '#components/ui/tabs.ts';
 ```
 
 ```ts
 // app/some-page/page.ts (uses the registered elements)
-import { buttonClass } from '../../components/ui/button.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 return html`
   <ui-dialog>
@@ -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 };
 }
 ```
@@ -791,7 +806,7 @@ with a `route.ts` POST handler:
 ```ts
 // app/posts/route.ts
 import { redirect, html } from '@webjsdev/core';
-import { createPost } from '../../modules/posts/actions/create-post.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
 
 export async function POST(req: Request) {
   const form = await req.formData();
@@ -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.

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.
 
 ---
@@ -382,10 +388,11 @@ modules/
 ```
 
 **Rules:**
+- **Prefer the `#` root alias over deep relatives.** Write `import { db } from '#db/connection.server.ts'`, `import { Button } from '#components/ui/button.ts'`, `#lib/...`, `#modules/...` instead of `../../../`. It is native `package.json "imports"` (the single `"#*": "./*"` key covers every top-level folder, so a new folder needs no config), resolved by Node and Bun with no build step. There is no slash after the `#` (`#lib/...`, not `#/lib/...`). A same-directory import stays relative (`./sibling.ts`).
 - 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).
 
@@ -582,8 +589,8 @@ the module once (typically in `app/layout.ts`) and use the tag.
 ```ts
 // Tier 1: class helpers on native elements (use this for forms,
 // dashboards, cards, layouts, anywhere the value is purely visual)
-import { buttonClass } from '../components/ui/button.ts';
-import { inputClass } from '../components/ui/input.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 return html`
   <button class=${buttonClass({ size: 'lg' })}>Save</button>
   <input class=${inputClass()} placeholder="Email">
@@ -767,7 +774,7 @@ Consume:
 
 ```ts
 // app/page.ts
-import { rubric } from '../lib/utils/ui.ts';
+import { rubric } from '#lib/utils/ui.ts';
 
 export default function Home() {
   return html`
@@ -919,15 +926,18 @@ 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;
 }
 ```
 
 ```ts
 // app/api/posts/route.ts
 import { route } from '@webjsdev/server';
-import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
 // The route() adapter merges query + route params + JSON body into one input
 // object and JSON-responds the result. Pass { validate } to guard the input.
 export const POST = route(createPost);
@@ -1030,7 +1040,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 +1159,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):**
@@ -1157,8 +1168,8 @@ Routes are thin wrappers over typed server actions. Business logic lives in
 
 ```ts
 // app/api/users/route.ts: thin wrapper
-import { listUsers } from '../../../modules/users/queries/list-users.server.ts';
-import { createUser } from '../../../modules/users/actions/create-user.server.ts';
+import { listUsers } from '#modules/users/queries/list-users.server.ts';
+import { createUser } from '#modules/users/actions/create-user.server.ts';
 
 export async function GET() { return Response.json(await listUsers()); }
 export async function POST(req: Request) {

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/templates/test/hello/hello.test.ts

@@ -16,7 +16,7 @@ test('html template renders correctly', async () => {
 
 test('example: your first server action test', async () => {
   // Import your server action:
-  // import { createPost } from '../../modules/posts/actions/create-post.server.ts';
+  // import { createPost } from '#modules/posts/actions/create-post.server.ts';
   //
   // const result = await createPost({ title: 'Test', body: 'Content' });
   // assert.equal(result.success, true);