@pylonsync/create-pylon 0.3.248 → 0.3.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.248",
+  "version": "0.3.250",
   "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,7 +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. The SAME earned render is also kept in an **origin disk cache** (`.pylon/.cache/ssr`): a cookie-less GET with no query string is served straight off disk for the TTL — skipping the render entirely — then re-rendered live when stale. The disk cache is namespaced per deploy (wiped on each new build) and OFF in `pylon dev` (so an edit is never masked by a stale entry); invalidation is by the `revalidate` TTL or the next deploy.
+- **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).
+- **`export const streaming = true` streams a page's OWN inner `<Suspense>` boundaries.** Without it (and without a `loading.tsx`), a page is BUFFERED — the whole document, including suspended children, resolves before the first byte. Opt in and the shell + each inner `<Suspense>` fallback flush immediately, then each boundary's real content streams in as its data resolves (multi-boundary progressive streaming). It's opt-in because it changes the response timing contract: a streaming render commits its HTTP head BEFORE suspended subtrees finish, so (a) it's never CDN/disk cacheable — don't combine with `export const revalidate`; (b) `response.setStatus/setCookie/redirect/notFound` only take effect from the SYNCHRONOUS shell render — a call from inside a suspended subtree is dropped (the runtime logs a loud warning naming what was lost); (c) a `throw` from a deep `<Suspense>` child resolves via its nearest `error.tsx` at HTTP 200, not a 5xx. Hydration is clean for any number of boundaries (the data blob ships before hydration runs). Type the config with `import type { RouteSegmentConfig } from "@pylonsync/react"`.
 - **`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.

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,
@@ -16,6 +22,15 @@ export const metadata: Metadata = {
     "A list of notes read from the database during the server render — no client fetch, no loading flash.",
 };
 
+// Progressive streaming opt-in (#278). With this, the page shell — heading,
+// blurb, the <Form> — flushes to the browser IMMEDIATELY, and the inner
+// <Suspense> around <NotesList> streams in its "Loading notes…" fallback,
+// then swaps in the real rows when serverData resolves. Without it, the whole
+// page (including the notes) is buffered and arrives in one shot. Streaming
+// pages are never CDN/disk-cached (the head commits before the data resolves),
+// so don't combine it with `export const revalidate`.
+export const streaming = true;
+
 // The `Note` entity from app.ts. Type your rows however you like; the
 // shape is whatever your entity declares.
 interface Note {
@@ -77,7 +92,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 +106,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");
+};