@pylonsync/create-pylon 0.3.246 → 0.3.248

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.246",
+  "version": "0.3.248",
   "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/ssr/AGENTS.md

@@ -23,6 +23,11 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 ## Key gotchas
 
 - **Policies deny by default; server functions BYPASS them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full DB access — enforce trust with `ctx.auth` checks inside the handler, not policies.
+- **Type page props from the SDK, don't hand-roll them.** `import type { PageProps, Metadata } from "@pylonsync/react"`. Every page/layout gets `{ url, params, searchParams, auth, response, serverData }`; `PageProps<{ slug: string }>` types a `[slug]` route's params. Request headers/cookies are intentionally NOT on `PageProps` — they're server-only and stripped from hydration, so reading them in the render would mismatch.
+- **`loading.tsx` streams a skeleton while the page's data resolves.** Drop `app/.../loading.tsx` (default export, page props) and the nearest one becomes a route-level Suspense fallback: Pylon flushes the shell + skeleton immediately, then reveals the real page when its top-level `use(serverData…)` resolves (no blank page). It only shows when the PAGE suspends — a page that wraps its own `<Suspense>` around a child (like `/notes`) handles that itself. The skeleton is SERVER-ONLY: don't read `serverData` in it. A page with no `loading.tsx` is buffered (unchanged).
+- **`error.tsx` / `not-found.tsx` boundaries are HYDRATED (interactive).** `app/.../error.tsx` catches a throw below it (HTTP 500) and receives `{ error: { message, digest }, reset }` (`import type { ErrorBoundaryProps }`) — `reset()` re-attempts the route; the stack NEVER reaches the client (dev overlay + logs only). `app/.../not-found.tsx` renders at 404 (also for `response.notFound()`) and gets the page props (`NotFoundProps`), no `reset`. Both run useState/onClick/hooks.
+- **Client navigation hooks live in @pylonsync/react.** `useRouter()` → `{ push, replace, back, forward, refresh, prefetch }`; `useSearchParams()` → reactive `URLSearchParams`; `usePathname()` → reactive pathname. The hooks are CLIENT-reactive — during SSR they return defaults (empty params / "/"); for server-side URL values read the `url` / `searchParams` page props.
+- **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"` — `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready — status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
 - **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db` — use `ctx.runQuery` / `ctx.runMutation`.

package/templates/ssr/app/counter/page.tsx

@@ -1,11 +1,7 @@
 import React from "react";
+import type { PageProps } from "@pylonsync/react";
 import { Button } from "@/components/ui/button";
 
-interface PageProps {
-  url: string;
-  searchParams: Record<string, string>;
-}
-
 // `app/counter/page.tsx` → `/counter`. This page is server-rendered AND
 // interactive: the HTML arrives with the initial count already in it (try
 // /counter?start=10), then the per-route chunk hydrates and useState takes

package/templates/ssr/app/error.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { type ErrorBoundaryProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+
+// `app/error.tsx` → the error boundary for this segment. It catches a throw
+// in any page/layout below it and renders at HTTP 500. It's HYDRATED, so
+// this is a real interactive client component: `reset()` re-attempts the
+// route, and useState/onClick work. The thrown error reaches the client as
+// `{ message, digest }` only — the stack stays in the dev overlay
+// (PYLON_DEV_MODE) and the server logs, never in the page.
+export default function Error({ error, reset }: ErrorBoundaryProps) {
+  const [tries, setTries] = React.useState(0);
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">
+          Something went wrong
+        </h1>
+        <p className="mt-2 text-muted-foreground">{error.message}</p>
+        {error.digest ? (
+          <p className="mt-1 text-xs text-muted-foreground/70">
+            Reference: <code>{error.digest}</code>
+          </p>
+        ) : null}
+      </section>
+      <div className="flex items-center gap-3">
+        <Button
+          onClick={() => {
+            setTries((n) => n + 1);
+            reset();
+          }}
+        >
+          Try again
+        </Button>
+        {tries > 0 ? (
+          <span className="text-sm text-muted-foreground">
+            Retried {tries} {tries === 1 ? "time" : "times"}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/templates/ssr/app/layout.tsx

@@ -1,20 +1,14 @@
 import React from "react";
-import { Link } from "@pylonsync/react";
-
-// Auth shape injected by the SSR runtime. `auth.user_id` is null for
-// anonymous visitors. Wire a sign-in flow with @pylonsync/client when
-// you're ready — for now this just shows the session state.
-interface AuthShape {
-  user_id: string | null;
-  is_admin: boolean;
-  tenant_id: string | null;
-  roles: string[];
-}
+import { Link, type PageAuth } from "@pylonsync/react";
 
+// A layout receives the page props plus `children`. `auth.user_id` is null
+// for anonymous visitors — wire a sign-in flow with @pylonsync/client when
+// you're ready; for now this just shows the session state. The `PageAuth`
+// type is exported from @pylonsync/react so you never hand-roll it.
 interface LayoutProps {
   children: React.ReactNode;
   url: string;
-  auth: AuthShape;
+  auth: PageAuth;
 }
 
 // The root layout wraps every page. It receives `url` and `auth` from the
@@ -50,6 +44,9 @@ export default function RootLayout({ children, url, auth }: LayoutProps) {
               <Link href="/counter" className="hover:text-foreground">
                 Counter
               </Link>
+              <Link href="/notes" className="hover:text-foreground">
+                Notes
+              </Link>
               <span
                 className={signedIn ? "text-emerald-600" : "text-muted-foreground/60"}
                 title={url}

package/templates/ssr/app/not-found.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import { Link, useRouter, type NotFoundProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+
+// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when
+// a page calls `response.notFound()`). It's HYDRATED, so it's interactive:
+// the buttons below use the client router. Not-found boundaries receive the
+// standard page props (and, matching Next, no `reset`).
+export default function NotFound(_props: NotFoundProps) {
+  const router = useRouter();
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">404</h1>
+        <p className="mt-2 text-muted-foreground">
+          We couldn&apos;t find that page.
+        </p>
+      </section>
+      <div className="flex items-center gap-3">
+        <Button onClick={() => router.back()} variant="outline">
+          ← Go back
+        </Button>
+        <Button asChild>
+          <Link href="/">Home</Link>
+        </Button>
+      </div>
+    </div>
+  );
+}

package/templates/ssr/app/notes/page.tsx

@@ -0,0 +1,115 @@
+import React, { Suspense, use } from "react";
+import { type Metadata, type PageProps, type ServerData } from "@pylonsync/react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+
+// SEO metadata for `/notes`. (`generateMetadata(props)` is the dynamic
+// form when the title depends on params — e.g. a `[slug]` route.)
+export const metadata: Metadata = {
+  title: "Notes — __APP_NAME__",
+  description:
+    "A list of notes read from the database during the server render — no client fetch, no loading flash.",
+};
+
+// The `Note` entity from app.ts. Type your rows however you like; the
+// shape is whatever your entity declares.
+interface Note {
+  id: string;
+  body: string;
+  done: boolean;
+}
+
+// This component reads the database DURING the render. `serverData.list`
+// returns a promise; React 19 `use()` suspends the subtree until it
+// resolves on the server, then the HTML streams with the rows already in
+// it — no `useEffect`, no client round-trip, no loading flash on first
+// paint. The resolved value is replayed into the hydration payload, so the
+// browser renders the exact same markup. Reads run through the same policy
+// gate as a query function's `ctx.db`; writes are rejected.
+function NotesList({ serverData }: { serverData: ServerData }) {
+  const notes = use(serverData.list<Note>("Note"));
+
+  if (notes.length === 0) {
+    return (
+      <p className="text-sm text-muted-foreground">
+        No notes yet. Create one through the auto-generated API:{" "}
+        <code className="rounded bg-muted px-1">
+          curl -X POST localhost:8787/api/entities/Note -d
+          '{"{"}"body":"hello"{"}"}'
+        </code>{" "}
+        then refresh.
+      </p>
+    );
+  }
+
+  return (
+    <ul className="space-y-2">
+      {notes.map((note) => (
+        <li
+          key={note.id}
+          className="flex items-center gap-3 rounded-md border px-3 py-2 text-sm"
+        >
+          <span
+            aria-hidden
+            className={
+              note.done
+                ? "text-emerald-600"
+                : "text-muted-foreground/50"
+            }
+          >
+            {note.done ? "✓" : "○"}
+          </span>
+          <span className={note.done ? "line-through text-muted-foreground" : ""}>
+            {note.body}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// `app/notes/page.tsx` → `/notes`. The page destructures `serverData` out
+// of its `PageProps` and hands it to the suspending child. (The same props
+// carry `response` for status/redirect/cookies and `params`/`searchParams`
+// for the URL — all typed, all from @pylonsync/react.)
+export default function NotesPage({ serverData }: PageProps) {
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">Notes</h1>
+        <p className="mt-2 text-muted-foreground">
+          These rows are read from the database <em>during the server
+          render</em> with <code>serverData</code> + React&apos;s{" "}
+          <code>use()</code>. The HTML arrives with the data in it — view
+          source and you&apos;ll see the notes in the markup, not an empty
+          shell that fetches later.
+        </p>
+      </section>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>From the database</CardTitle>
+          <CardDescription>
+            Server-rendered, then hydrated. Edit{" "}
+            <code className="rounded bg-muted px-1">app.ts</code> to change
+            the <code className="rounded bg-muted px-1">Note</code> shape.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Suspense
+            fallback={
+              <p className="text-sm text-muted-foreground">Loading notes…</p>
+            }
+          >
+            <NotesList serverData={serverData} />
+          </Suspense>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/templates/ssr/app/page.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Link } from "@pylonsync/react";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
 import { Button } from "@/components/ui/button";
 import {
   Card,
@@ -9,15 +9,23 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 
-interface PageProps {
-  url: string;
-}
+// SEO metadata. Export `metadata` (static) or `generateMetadata(props)`
+// (dynamic) from any page or layout — Pylon renders the <title>/<meta>
+// into <head> server-side. The `Metadata` type is exported from
+// @pylonsync/react.
+export const metadata: Metadata = {
+  title: "__APP_NAME__ — full-stack Pylon app",
+  description:
+    "Server-rendered React, file-based routes, a synced database, and a typed client — one binary, one port.",
+};
 
-// `app/page.tsx` → `/`. Pages receive `{ url, auth, searchParams }` from
-// the SSR runtime. This renders to HTML on the server; the per-route
-// chunk hydrates it in the browser so interactive pages (see /counter)
-// just work. shadcn/ui is pre-wired — `Button`/`Card` resolve through the
-// `@/` alias and add more with `npx shadcn@latest add <component>`.
+// `app/page.tsx` → `/`. Every page receives `PageProps` from the SSR
+// runtime: `{ url, params, searchParams, auth, response, serverData }` —
+// the type is exported from @pylonsync/react, no hand-rolled interface.
+// This renders to HTML on the server; the per-route chunk hydrates it in
+// the browser so interactive pages (see /counter) just work. shadcn/ui is
+// pre-wired — `Button`/`Card` resolve through the `@/` alias; add more with
+// `npx shadcn@latest add <component>`.
 export default function IndexPage({ url }: PageProps) {
   return (
     <div className="space-y-8">
@@ -68,6 +76,9 @@ export default function IndexPage({ url }: PageProps) {
           <Link href="/counter">See hydration in action →</Link>
         </Button>
         <Button asChild variant="outline">
+          <Link href="/notes">Server data in the render →</Link>
+        </Button>
+        <Button asChild variant="ghost">
           <a
             href="https://docs.pylon.dev"
             target="_blank"