CLAUDE.md · diff

git:20260427.5a158e3 to git:20260511.b5f16b6

39 added, 81 removed. Audit A to A.

# CLAUDE.md

- **Do not duplicate content here.** This file points to authoritative sources

- and defines the AI-driven development workflow for the webjs framework itself.

- ## Required reading

- 1. **[`AGENTS.md`](./AGENTS.md)** — The authoritative contract. Defines: what

- webjs is, file conventions, public API surface, directives, lifecycle,

- controllers, context, task, invariants, recipes, security, testing,

- conventions, advanced features. **Read it before editing anything.**

- ## AI-driven development workflow (non-negotiable)

- **Before starting ANY work:**

- 1. `git branch --show-current` — if on `main`, create a feature branch

- 2. `git fetch origin && git log HEAD..origin/main --oneline` — rebase if behind

- 3. Verify the branch matches the task at hand

- **Autonomous mode (sandbox/bypass):** Don't ask questions. Auto-create

- branches, auto-rebase, auto-merge + delete feature branches, auto-generate

- commit messages, fix failing tests and violations. Same quality bar.

- **Every change to this framework MUST include — automatically, without the

- user asking:**

- ### 1. Commit and push often

- **Commit AND push after each logical unit of work** — a completed

- feature, a passing test, a doc update. Don't accumulate uncommitted

- or unpushed changes. Small focused commits with meaningful messages.

- No AI attribution trailers. Always `git push` after committing.

- ### 2. Tests

- - **Unit tests** in `test/*.test.js` for any new/changed functionality

- - **E2E tests** in `test/browser/` for user-facing features

- - Run `npm test` after every change. Run `npm run test:browser` for E2E.

- - Never report work as done with failing tests.

- ### 3. Documentation

+ This file is a thin pointer. **All authoritative content lives in

+ [`AGENTS.md`](./AGENTS.md)** — workflow, conventions, public API, file

+ layout, recipes, invariants, autonomous-mode behaviour, scaffold rules,

+ testing requirements, git rules. Read AGENTS.md before doing anything.

- When adding or modifying framework features, update:

+ The full hosted documentation is at **https://docs.webjs.com**. Reach

+ for it when AGENTS.md doesn't cover something.

- - **`AGENTS.md`** — API surface, directive table, lifecycle docs, recipes

- - **`docs/`** — Add or update the relevant documentation page

- - **`website/`** — Update the landing page for marketable features

- - **`examples/blog/`** — Update the blog to use the new feature so E2E

- tests exercise it

- - **`packages/cli/templates/`** — Update CONVENTIONS.md/CLAUDE.md templates

- if the change affects what scaffolded apps should know

+ ---

- ### 4. Convention validation

+ The rest of this file is for context that is **specific to the webjs

+ framework repo** (i.e. the monorepo you're inside right now) and that

+ intentionally does NOT belong in AGENTS.md — because AGENTS.md is shipped

+ into scaffolded apps and these details are about developing the

+ framework itself.

- Run `webjs check` on the blog example after changes.

+ ## Framework-dev language rules (do NOT apply to scaffolded apps)

- ## Framework philosophy

+ - **`packages/`** — framework source. Plain `.js` with JSDoc types only.

+ Never add `.ts` files here.

+ - **`examples/`, `docs/`, `website/`** — apps consuming the framework.

+ TypeScript is fine and encouraged.

- - **Opinionated defaults.** In-memory cache in dev; one `setStore(redisStore({ url: process.env.REDIS_URL }))` call at startup switches cache/sessions/rate-limit to Redis for horizontal scaling. No config files.

- - **Built-in essentials: auth (OAuth + credentials + JWT), sessions (cookie or Redis), cache() for queries, HTTP Cache-Control, WebSocket broadcast(), rateLimit().

- - **Less is more** for abstractions (directives, lifecycle hooks) — only what has no native workaround.

- - **No build step by default.** Never introduce a bundler in the critical path.

- - **JSDoc types in framework code** (packages/). Do not add `.ts` files there.

- - **TypeScript in examples/apps** (examples/blog, docs, website). `.ts` is fine.

- - **Web components first.** Shadow DOM scoped styles via `static styles = css`.

- - **Commits**: do NOT add a `Co-Authored-By: Claude…` trailer.

+ (Scaffolded apps default to TypeScript — see `AGENTS.md`. This split

+ exists because the framework itself stays buildless / no-tsc.)

- ## Common commands

+ ## Framework-repo commands

```sh

npm install # workspace-linked deps

- npm test # run unit tests (153 tests)

- npm run test:browser # run E2E tests (9 tests, needs chromium)

+ npm test # run unit tests

+ npm run test:browser # E2E tests (needs Chromium)

npm run dev # website + docs + blog together (5000/4000/3456)

- cd website && npm run dev # just the website (port 5000)

- cd docs && npm run dev # just the docs (port 4000)

- cd examples/blog && npm run dev # just the blog (port 3456)

- # scaffold

- webjs create <name> # full-stack app (default)

- webjs create <name> --template api # backend-only API app

- webjs create <name> --template saas # auth + dashboard + Prisma User model

+ cd website && npm run dev # just the website (port 5000)

+ cd docs && npm run dev # just the docs (port 4000)

+ cd examples/blog && npm run dev # just the blog (port 3456)

```

- ## Reference codebases

+ ## When a framework change lands, update

- Cloned locally at `~/Documents/Projects/` for architectural reference:

+ - `AGENTS.md` if the public API / directive / lifecycle / convention surface changed

+ - `docs/` for the user-facing doc page

+ - `website/` if the change is marketable on the landing page

+ - `examples/blog/` so E2E tests exercise the new path

+ - `packages/cli/templates/` if scaffolded apps should know about it

- - **`lit`** — [Lit](https://lit.dev): web-component-first JS library.

- Compare: rendering, hydration, component lifecycle, directives.

- - **`remix`** — [Remix](https://remix.run) v3: AI-first web framework

- (under active development). Compare: module loading, streaming SSR,

- hydration data delivery.

- - **`turbo`** — [Turbo](https://turbo.hotwired.dev): Turbo Drive library.

- Compare: link interception, body swap, history, View Transitions.

- - **`next.js`** — [NextJs](https://nextjs.org): React framework with

- App Router. Compare: file conventions, routing, layouts, metadata,

- loading states, streaming SSR. webjs's router is at near-parity.

+ ## Reference codebases (local, on this machine)

+ Cloned at `~/Documents/Projects/` for architectural comparison:

+ - **`lit`** — [Lit](https://lit.dev): rendering, hydration, lifecycle, directives.

+ - **`remix`** — [Remix](https://remix.run) v3: module loading, streaming SSR, hydration data.

+ - **`turbo`** — [Turbo](https://turbo.hotwired.dev): link interception, body swap, View Transitions.

+ - **`next.js`** — [Next.js](https://nextjs.org): App Router file conventions, layouts, metadata.