@pylonsync/create-pylon 0.3.247 → 0.3.249

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.247",
+  "version": "0.3.249",
   "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

@@ -24,6 +24,10 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 - **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.
+- **Anonymous output caching is opt-in + earned.** `export const revalidate = 60` (seconds) on a page makes it CDN-cacheable (`public, s-maxage=60`) — but ONLY if the render is auth-INDEPENDENT: it must NOT read `props.auth` (reading it at all opts out, even for anonymous), set no cookie, and the app must not run strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. Fail-closed: without the opt-in (or if any condition fails) the page is `no-cache`. A page that reads `auth` or sets a cookie is never shared.
+- **No-JS forms use `route.ts` + `<Form>`.** Drop `app/.../route.ts` exporting `export const POST: RouteHandler = async ({ form, db, response, auth }) => { await db.insert("X", {...}); response.redirect("/x?ok=1"); }` (303 POST-redirect-GET by default). Render `<Form action="/x">` (from @pylonsync/react) with plain `<input name=...>` — works with JS off (native POST→handler→redirect) and is enhanced to no-reload when JS is on. The handler's `db` is read+write (mutation trust model — gate on `auth`); CSRF is automatic (Origin gate + SameSite=Lax). Multipart/file uploads aren't supported yet — use urlencoded forms + `/api/files`.
+- **`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.

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/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

@@ -1,5 +1,11 @@
 import React, { Suspense, use } from "react";
-import { type Metadata, type PageProps, type ServerData } from "@pylonsync/react";
+import {
+  Form,
+  type Metadata,
+  type PageProps,
+  type ServerData,
+} from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
 import {
   Card,
   CardContent,
@@ -77,7 +83,7 @@ function NotesList({ serverData }: { serverData: ServerData }) {
 // 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) {
+export default function NotesPage({ serverData, searchParams }: PageProps) {
   return (
     <div className="space-y-6">
       <section>
@@ -91,6 +97,29 @@ export default function NotesPage({ serverData }: PageProps) {
         </p>
       </section>
 
+      {/* No-JS form (#276). Posts to app/notes/route.ts, which creates a Note
+          and 303-redirects back here. Works with JS disabled; the runtime
+          enhances it (no full reload) when JS is on. */}
+      {searchParams.created ? (
+        <p className="rounded-md border border-emerald-600/30 bg-emerald-600/10 px-3 py-2 text-sm text-emerald-700">
+          Note added.
+        </p>
+      ) : null}
+      {searchParams.error ? (
+        <p className="rounded-md border border-red-600/30 bg-red-600/10 px-3 py-2 text-sm text-red-700">
+          {searchParams.error}
+        </p>
+      ) : null}
+      <Form action="/notes" className="flex items-center gap-2">
+        <input
+          name="body"
+          placeholder="Write a note…"
+          aria-label="Note"
+          className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        />
+        <Button type="submit">Add</Button>
+      </Form>
+
       <Card>
         <CardHeader>
           <CardTitle>From the database</CardTitle>

package/templates/ssr/app/notes/route.ts

@@ -0,0 +1,21 @@
+import { type RouteHandler } from "@pylonsync/react";
+
+// `app/notes/route.ts` → handles POST /notes (the same path the page lives at).
+// A `<Form action="/notes">` posts here; we create a Note, then 303-redirect
+// back to /notes (POST-redirect-GET) so a no-JS browser re-renders with the new
+// note. Validation errors round-trip through a query param. With JS, the
+// runtime intercepts the submit + swaps the page in without a full reload —
+// same handler, no extra code.
+//
+// CSRF is automatic: Pylon's Origin gate rejects cross-site POSTs before this
+// runs, and the session cookie is SameSite=Lax. Writes here use the normal
+// function trust model — gate sensitive actions on `auth` inside the handler.
+export const POST: RouteHandler = async ({ form, db, response }) => {
+  const body = (form.get("body") ?? "").trim();
+  if (!body) {
+    response.redirect("/notes?error=" + encodeURIComponent("Note can't be empty"));
+    return;
+  }
+  await db.insert("Note", { body });
+  response.redirect("/notes?created=1");
+};