@pylonsync/create-pylon 0.3.284 → 0.3.286

package/bin/create-pylon.js

@@ -465,6 +465,12 @@ function walkAndSubstitute(dir) {
 		// scaffold time — otherwise the new project has no ignore file
 		// and node_modules / .pylon / *.db get committed.
 		if (renamed === "gitignore") renamed = ".gitignore";
+		// `bun publish` (which the release uses) strips a literal
+		// `bunfig.toml` — it treats it as Bun's own runtime config and
+		// refuses to ship it in a package. Templates ship it as `bunfig`
+		// and we restore the `.toml` here, so the happy-dom test preload
+		// actually lands and component tests can render.
+		if (renamed === "bunfig") renamed = "bunfig.toml";
 		let target = abs;
 		if (renamed !== entry) {
 			target = join(dir, renamed);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.284",
+  "version": "0.3.286",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"

package/templates/_root/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -50,4 +50,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/agency/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -39,9 +39,9 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
 
-**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,25 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against production).
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -61,16 +79,14 @@ import { resetDb } from "@pylonsync/functions";
 const BASE = "http://localhost:4321";
 afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
 
-test("createThing then it shows up", async () => {
-  const created = await fetch(`${BASE}/api/fn/createThing`, {
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: "hello" }),
   }).then((r) => r.json());
-  expect(created.name).toBe("hello");
-
   const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
-  expect(rows.some((t: { id: string }) => t.id === created.id)).toBe(true);
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
 });
 ```
 
@@ -97,4 +113,4 @@ test("createThing then it shows up", async () => {
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/agency/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/agency/package.json

@@ -28,6 +28,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/agency/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/agency/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/ai-chat/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -39,9 +39,9 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
 
-**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,25 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against production).
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -61,16 +79,14 @@ import { resetDb } from "@pylonsync/functions";
 const BASE = "http://localhost:4321";
 afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
 
-test("createThing then it shows up", async () => {
-  const created = await fetch(`${BASE}/api/fn/createThing`, {
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: "hello" }),
   }).then((r) => r.json());
-  expect(created.name).toBe("hello");
-
   const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
-  expect(rows.some((t: { id: string }) => t.id === created.id)).toBe(true);
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
 });
 ```
 
@@ -97,4 +113,4 @@ test("createThing then it shows up", async () => {
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/ai-chat/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/ai-chat/package.json

@@ -27,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/ai-chat/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/ai-studio/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -39,9 +39,9 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
 
-**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,25 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against production).
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -61,16 +79,14 @@ import { resetDb } from "@pylonsync/functions";
 const BASE = "http://localhost:4321";
 afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
 
-test("createThing then it shows up", async () => {
-  const created = await fetch(`${BASE}/api/fn/createThing`, {
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: "hello" }),
   }).then((r) => r.json());
-  expect(created.name).toBe("hello");
-
   const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
-  expect(rows.some((t: { id: string }) => t.id === created.id)).toBe(true);
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
 });
 ```
 
@@ -97,4 +113,4 @@ test("createThing then it shows up", async () => {
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/ai-studio/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/ai-studio/package.json

@@ -27,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/ai-studio/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/barebones/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -39,9 +39,9 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
 
-**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,25 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against production).
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -61,16 +79,14 @@ import { resetDb } from "@pylonsync/functions";
 const BASE = "http://localhost:4321";
 afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
 
-test("createThing then it shows up", async () => {
-  const created = await fetch(`${BASE}/api/fn/createThing`, {
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: "hello" }),
   }).then((r) => r.json());
-  expect(created.name).toBe("hello");
-
   const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
-  expect(rows.some((t: { id: string }) => t.id === created.id)).toBe(true);
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
 });
 ```
 
@@ -97,4 +113,4 @@ test("createThing then it shows up", async () => {
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/barebones/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/barebones/package.json

@@ -27,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^5.6.0"

package/templates/barebones/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/barebones/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/chat/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -39,9 +39,9 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
 
-**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,25 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against production).
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -61,16 +79,14 @@ import { resetDb } from "@pylonsync/functions";
 const BASE = "http://localhost:4321";
 afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
 
-test("createThing then it shows up", async () => {
-  const created = await fetch(`${BASE}/api/fn/createThing`, {
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: "hello" }),
   }).then((r) => r.json());
-  expect(created.name).toBe("hello");
-
   const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
-  expect(rows.some((t: { id: string }) => t.id === created.id)).toBe(true);
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
 });
 ```
 
@@ -97,4 +113,4 @@ test("createThing then it shows up", async () => {
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/chat/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/chat/package.json

@@ -27,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^5.6.0"

package/templates/chat/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/chat/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();