@pylonsync/create-pylon 0.3.248 → 0.3.249

package/package.json

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

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");
+};