AGENTS.md@packages/cli/templates ยท diff
git:20260725.e07ea3a to git:20261007.f948b91
42 added, 46 removed. Audit A to A.
# AGENTS.md for {{APP_NAME}}
- This is a WebJs app: AI-first, web-components-first, buildless, and
- progressively enhanced. Read this whole file before you edit anything, then
- follow it. The steps here are required, not optional.
-
- ## Gather context BEFORE you build (required)
-
- WebJs is its own framework. It is not React, Next, or Lit, so writing code from
- that muscle memory produces broken WebJs code. Before you write or change
- anything, gather context from these sources. Do not skip a step to save time.
- This is what separates a working app from a broken one.
-
- 1. **Read the skill.** Start with `.agents/skills/webjs/SKILL.md`, then load the
- `references/*.md` files it routes to for the surface you are touching. The
- skill is the guide to building a WebJs app: it helps you choose the right
- layer, reach for the right export, and avoid the mistakes Next.js or Lit
- habits cause. Reading it is never wasted work: it survives the
- gallery-clearing step in the playbook below.
- 2. **Study the shipped examples, then build on a clean slate.** The template
- playbook below says what ships and the exact order to follow. The workflow
- rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
- too.
- 3. **Read the framework source for exact contracts.** WebJs is 100% buildless
- native ES modules, so the source you run IS the source you read. When you
- need a precise API signature or behavior, open the package source under
- `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
- The full hosted docs are at https://webjs.dev/docs.
+ This is a WebJs app: server-rendered pages, web components for interactivity,
+ server actions, Drizzle, and no build step. WebJs is its own framework, not
+ React, Next.js or Lit, so write it from the patterns in this file rather than
+ from that memory. Read this whole file before you edit anything.
{{PLAYBOOK}}
- ## Type everything (all templates)
+ ## Rules that hold everywhere
- Define explicit TypeScript interfaces and discriminated unions for your data
- payloads and action inputs and outputs (and, in a UI app, component props and
- optimistic updates). Narrow an `ActionResult` with
- `if (result.success && result.data)`. Never reach for `any` or a loose
- `as any` cast.
+ - **Type every boundary from its source.** A row is
+ `typeof posts.$inferSelect` (exported from `db/schema.server.ts`, carried
+ into browser code with `import type`), an action's input is a named
+ `interface`, a routing file uses `PageProps<'/posts/[id]'>` / `LayoutProps` /
+ `RouteHandlerContext` from `@webjsdev/core`, and a component prop that holds
+ an object is `prop<Post>(Object)`. Never reach for `any` or `as any`, and
+ keep `unknown` for an untrusted payload you narrow on the next line.
+ - **Server-only code stays behind `.server.ts`.** A file WITH `'use server'`
+ exposes its exported async functions as actions; a file WITHOUT it is a
+ server-only utility that only other server code may import. Never add
+ `'use server'` to a file only server code imports (the DB connection, the
+ schema).
+ - **Store data with Drizzle** in the wired-up database (`db/`), never in a
+ JSON file, an in-memory array or Map, or localStorage. Every schema change is
+ `npm run db:generate` then `npm run db:migrate`, and the generated
+ migrations are committed.
+ - **TypeScript is erasable:** no `enum`, no `namespace`, no constructor
+ parameter properties, no decorators. Never put a backtick inside an
+ `html` template body, even in a comment.
+ - **Errors tell you the fix.** `npm run check` and `npm run typecheck` name
+ the file, the rule and the fix; do what they say rather than searching.
- Keep server-only code (database drivers, secrets, `node:*` builtins) in
- `.server.ts` modules. There are exactly two kinds:
+ ## Git
- - A `.server.ts` file WITH `'use server';` as its first line is a server
- action: WebJs exposes its exported async functions to browser code as RPC
- calls, so browser modules may import it directly.
- - A `.server.ts` file WITHOUT `'use server'` is a server-only utility:
- importing it from a page, layout, or component CRASHES in the browser at
- module load. Reach it only from `'use server'` actions, `route.ts` handlers,
- or middleware. Never add `'use server'` to a file only other server code
- imports (the DB connection, the schema).
+ Commit per logical unit (CLAUDE.md has the rule). When you build a whole app
+ from a spec in one session, the build is one unit: work on a feature branch
+ (commits to `main` are refused), and commit once at the end after the checks
+ pass (`git add -A && git commit -m "<imperative subject>"`). Team workflow
+ (pull requests, CI, worktrees) is in `.agents/rules/workflow.md`.
- ## Data (all templates)
+ ## When you need more
- Use the wired-up database (Drizzle) for every piece of data the app stores;
- the playbook above has the modeling step. Never store app data in a JSON file,
- an in-memory array, or localStorage.
+ The reference set is `.agents/skills/webjs/` (`SKILL.md` routes to
+ `references/*.md`). Open one only for a surface this file does not show:
+ streaming and Suspense (`client-router-and-streaming.md`), optimistic UI
+ (`optimistic-ui.md`), caching, rate limits, file uploads, env vars
+ (`built-ins.md`), OAuth providers and sessions (`auth-and-sessions.md`),
+ browser and e2e tests (`testing.md`), deeper component topics such as slots,
+ shadow DOM, context and directives (`components.md`). The exact framework
+ source is under `node_modules/@webjsdev/*`, and the hosted docs are at
+ https://webjs.dev/docs.