@rangojs/router 0.0.0-experimental.debug-cache-2383ca26 → 0.0.0-experimental.df7974ff

package/skills/server-actions/SKILL.md

@@ -0,0 +1,739 @@
+---
+name: server-actions
+description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation
+argument-hint: "[action]"
+---
+
+# Server Actions with `"use server"`
+
+Server actions are async functions that run on the server and are callable from
+the client. They are React's RSC mutation primitive — Rango uses them as-is
+with no framework wrapper. All standard React hooks (`useActionState`,
+`useFormStatus`, `useOptimistic`, `useTransition`) work directly.
+
+## When to Use Actions vs Loaders
+
+| Need                               | Use                                          |
+| ---------------------------------- | -------------------------------------------- |
+| Mutate state and revalidate UI     | Server action                                |
+| Read live data on every navigation | `createLoader()` + `useLoader()`             |
+| Read on demand from the client     | Fetchable loader + `useFetchLoader()`        |
+| Submit a form and show the result  | Action + `useActionState`                    |
+| File upload                        | Action with `FormData` (or fetchable loader) |
+
+Use loaders and route handlers for reads. Use actions for writes. After an
+action runs, the matched route tree can partially re-render so handlers and
+loaders that opt into revalidation see the new state — see "Revalidation"
+below.
+
+## Revalidation Model
+
+Actions mutate state; route handlers and loaders read the latest state. After
+an action finishes, Rango performs a server-side revalidation render for the
+matched route so the UI receives fresh segment output and loader data.
+
+The main control point is `revalidate(({ actionId }) => ...)` on the segment
+that owns the data. This applies to `path()` handlers, `layout()` handlers,
+`parallel()` slots, `intercept()` routes, and loader registrations:
+
+```typescript
+// urls.tsx — path/layout/parallel/intercept/loader/revalidate are passed in by urls()
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, loader, revalidate }) => [
+  // The loader belongs to the route that consumes its data — nest it inside
+  // the owning path() so the segment owns its data dependency.
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(
+      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+    ),
+    loader(CartLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+For module-level `"use server"` files, the `actionId` passed to every
+server-side `revalidate()` predicate is path-bearing in the server/RSC
+environment in both dev and production: `src/actions/cart.ts#addToCart`. This
+is intentional so path, layout, parallel, intercept, and loader revalidation
+predicates can filter by action file, directory, or export name.
+
+Actions and the follow-up revalidation render share one request context.
+Values written in the action with `ctx.set(MyVar, value)` or `ctx.set("key",
+value)` are visible to downstream route middleware, handlers, loaders, and
+`revalidate()` callbacks through `context.get(MyVar)` / `context.get("key")`:
+
+```typescript
+// app/context.ts
+import { createVar } from "@rangojs/router";
+
+export const ChangedTenant = createVar<string>();
+```
+
+```typescript
+// app/actions/tenant.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+import { ChangedTenant } from "../context";
+
+export async function switchTenant(tenantId: string) {
+  const ctx = getRequestContext();
+  ctx.set(ChangedTenant, tenantId);
+  await db.tenants.touch(tenantId);
+}
+```
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+import { ChangedTenant } from "./context";
+
+export const urlpatterns = urls(({ path, revalidate }) => [
+  path("/dashboard/:tenantId", DashboardPage, { name: "dashboard" }, () => [
+    revalidate(
+      ({ actionId, context }) =>
+        actionId?.startsWith("src/actions/tenant.ts#") &&
+        context.get(ChangedTenant) === context.params.tenantId,
+    ),
+  ]),
+]);
+```
+
+Client and SSR-facing action references keep hashed IDs in production for
+security and hydration compatibility. Do path matching inside server-side
+`revalidate()` predicates, not from client action metadata. Inline actions
+declared inside RSC components also keep hashed IDs; if you need path-based
+revalidation, export the action from a module-level `"use server"` file.
+
+## Defining an Action
+
+Two equivalent patterns. Prefer the file-level form for anything reusable.
+
+### File-level (`"use server"` at the top of a module)
+
+Every exported async function becomes a callable server action.
+
+```typescript
+// app/actions/cart.ts
+"use server";
+
+import { cookies } from "@rangojs/router";
+
+export async function addToCart(productId: string): Promise<void> {
+  const userId = cookies().get("user-id")?.value;
+  await db.cart.insert({ userId, productId });
+}
+
+export async function removeFromCart(productId: string): Promise<void> {
+  const userId = cookies().get("user-id")?.value;
+  await db.cart.delete({ userId, productId });
+}
+```
+
+### Inline (`"use server"` inside a server component)
+
+Define a one-off action where it is used. Captured variables are serialized,
+so keep them small and serializable.
+
+```tsx
+// Server component (handler)
+import type { Handler } from "@rangojs/router";
+
+const SettingsPage: Handler<"settings"> = (ctx) => {
+  const userId = ctx.get("user").id;
+
+  async function updateName(formData: FormData) {
+    "use server";
+    await db.users.update(userId, { name: formData.get("name") as string });
+  }
+
+  return (
+    <form action={updateName}>
+      <input name="name" />
+      <button type="submit">Save</button>
+    </form>
+  );
+};
+```
+
+## Calling Actions from the Client
+
+Three patterns, in order of how much state you need to preserve:
+
+### 1. Plain `<form action={...}>` — fire-and-forget
+
+Submits as `FormData`. Works without JavaScript (progressive enhancement).
+The page revalidates after the action returns.
+
+```tsx
+"use client";
+import { addToCart } from "../actions/cart";
+
+export function AddToCartForm({ productId }: { productId: string }) {
+  return (
+    <form action={addToCart.bind(null, productId)}>
+      <button type="submit">Add to cart</button>
+    </form>
+  );
+}
+```
+
+### 2. `useActionState` — preserve return value + pending state
+
+Standard React 19 hook. The action receives `(prevState, formData)` and its
+return value becomes the new `state`. The form input values are preserved by
+the browser on validation errors as long as you re-render the same form
+element with `defaultValue` (not `value`).
+
+Define the state shape next to the action so the client and server share
+one type:
+
+```typescript
+// app/actions/profile.ts
+"use server";
+
+export type ProfileFormState = {
+  errors?: Record<string, string>;
+  values?: { name: string };
+} | null;
+
+export async function saveProfile(
+  _prev: ProfileFormState,
+  formData: FormData,
+): Promise<ProfileFormState> {
+  const name = (formData.get("name") as string)?.trim() ?? "";
+  if (!name) {
+    return { errors: { name: "Name is required" }, values: { name } };
+  }
+  await db.users.update({ name });
+  return null; // success
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { saveProfile, type ProfileFormState } from "../actions/profile";
+
+export function ProfileForm({ initial }: { initial: { name: string } }) {
+  const [state, formAction, isPending] = useActionState<
+    ProfileFormState,
+    FormData
+  >(saveProfile, null);
+
+  return (
+    <form action={formAction}>
+      <input
+        name="name"
+        defaultValue={state?.values?.name ?? initial.name}
+        aria-invalid={!!state?.errors?.name}
+      />
+      {state?.errors?.name && <p role="alert">{state.errors.name}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving…" : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+**Why `defaultValue`, not `value`** — on validation error the form re-renders.
+With `value` the inputs reset; with `defaultValue` (and a stable form key) the
+browser keeps user input. Re-echo the submitted values in `state.values` so
+they survive a full no-JS re-render too.
+
+### 3. `useOptimistic` — instant UI before the action settles
+
+For reactive UI like quantity controls, like buttons, or todo toggles.
+Combine with `startTransition` so the optimistic update is part of the same
+transition as the action call.
+
+```tsx
+"use client";
+import { useOptimistic, startTransition } from "react";
+import { updateQuantity } from "../actions/cart";
+
+export function QuantityControl({
+  productId,
+  initialQuantity,
+}: {
+  productId: string;
+  initialQuantity: number;
+}) {
+  const [optimistic, setOptimistic] = useOptimistic(
+    initialQuantity,
+    (_current, next: number) => next,
+  );
+
+  function change(delta: number) {
+    const next = Math.max(0, optimistic + delta);
+    startTransition(async () => {
+      setOptimistic(next);
+      await updateQuantity(productId, delta);
+    });
+  }
+
+  return (
+    <div>
+      <button onClick={() => change(-1)}>-</button>
+      <span>{optimistic}</span>
+      <button onClick={() => change(1)}>+</button>
+    </div>
+  );
+}
+```
+
+`useOptimistic` resets to the real value once the surrounding transition
+settles and React re-renders with the post-action loader data.
+
+### `useFormStatus` — pending state in nested children
+
+When the submit button is in a separate component from the form, use
+`useFormStatus()` instead of threading `isPending` down via props.
+
+```tsx
+"use client";
+import { useFormStatus } from "react-dom";
+
+export function SubmitButton({ children }: { children: React.ReactNode }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? "Working…" : children}
+    </button>
+  );
+}
+```
+
+`useFormStatus` only reports the form it is rendered inside — it does not
+observe other forms.
+
+## Validation with Zod
+
+Validate on the server, return structured errors via `useActionState`. Keep
+the schema next to the action so client and server agree on the shape.
+
+```typescript
+// app/actions/signup.ts
+"use server";
+
+import { z } from "zod";
+import { redirect } from "@rangojs/router";
+
+const SignupSchema = z.object({
+  email: z.string().email("Enter a valid email"),
+  password: z.string().min(8, "At least 8 characters"),
+  name: z.string().min(1, "Required"),
+});
+
+export type SignupState = {
+  errors?: Partial<Record<keyof z.infer<typeof SignupSchema>, string>>;
+  values?: Partial<z.infer<typeof SignupSchema>>;
+} | null;
+
+export async function signup(
+  _prev: SignupState,
+  formData: FormData,
+): Promise<SignupState> {
+  const raw = {
+    email: formData.get("email") as string,
+    password: formData.get("password") as string,
+    name: formData.get("name") as string,
+  };
+
+  const parsed = SignupSchema.safeParse(raw);
+  if (!parsed.success) {
+    const errors: Record<string, string> = {};
+    for (const issue of parsed.error.issues) {
+      const key = String(issue.path[0]);
+      errors[key] ??= issue.message; // first error per field
+    }
+    // Echo back values (omit password) so the form preserves user input.
+    const { password: _drop, ...safeValues } = raw;
+    return { errors, values: safeValues };
+  }
+
+  await db.users.create(parsed.data);
+  throw redirect("/welcome");
+}
+```
+
+The form reads `state.errors` field-by-field and re-uses `state.values` as
+`defaultValue`s (see `useActionState` example above). Never echo back
+secrets like passwords.
+
+For schemas shared with a `useFetchLoader()` JSON body, parse the same way:
+
+```typescript
+const parsed = SignupSchema.safeParse(ctx.body);
+```
+
+## Revalidation After an Action
+
+When an action mutates data, the matched route tree may need to partially
+re-render so the UI updates. Rango runs the action, then evaluates
+`revalidate()` on matched segments and loaders. Each path, layout, parallel,
+intercept, or loader rule decides whether that piece re-renders/re-resolves.
+
+The `actionId` arrives as part of the revalidation context — match it to
+scope re-runs to specific actions.
+
+```typescript
+// urls.tsx — inside the urls() callback. Nest each loader inside the path(),
+// layout(), or parallel() that owns its data so the route tree mirrors the
+// data dependencies.
+urls(({ path, loader, revalidate }) => [
+  path("/", HomePage, { name: "home" }, () => [
+    // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
+    loader(StaticHomepageLoader, () => [revalidate(() => false)]),
+  ]),
+
+  // Re-render the cart page handler AND re-resolve its loader after cart actions
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(
+      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+    ),
+    loader(CartLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+      ),
+    ]),
+  ]),
+
+  // Re-run after any action under src/actions/account/
+  path("/account", AccountPage, { name: "account" }, () => [
+    loader(AccountLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/account/") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+`actionId` is stable per action. For actions exported from a module-level
+`"use server"` file, the ID is prefixed with the source file path
+(`src/actions/cart.ts#addToCart`), so substring matching by file path is the
+recommended scope. **Inline `"use server"` actions** (declared inside an RSC
+component) intentionally keep their hashed IDs — file paths are withheld
+from the client for security. If you need file-path-based revalidation
+predicates, define the action in a module-level `"use server"` file rather
+than inline. See `/loader` for the full revalidation contract (deferred
+returns, soft suggestions).
+
+### Cross-segment dependencies
+
+If a loader reads `ctx.get()` data set by an outer layout/handler, that
+outer segment must also re-run after the action — otherwise the loader sees
+stale context. Share the same `revalidate` predicate on both producer and
+consumer:
+
+```typescript
+const revalidateCart = ({ actionId }) =>
+  actionId?.startsWith("src/actions/cart.ts#") ?? false;
+
+urls(({ path, layout, loader, revalidate }) => [
+  layout(CartLayout, () => [
+    revalidate(revalidateCart), // producer reruns
+    path("/cart", CartPage, { name: "cart" }, () => [
+      loader(CartItemsLoader, () => [revalidate(revalidateCart)]), // consumer reruns
+    ]),
+  ]),
+]);
+```
+
+See `/middleware` for the full cross-segment revalidation contract.
+
+## Redirects
+
+`redirect()` works inside actions. Both `return redirect(...)` and
+`throw redirect(...)` are supported and behave the same way for the
+client. Throwing is clearer when the redirect is conditional.
+
+```typescript
+"use server";
+
+import { redirect, cookies } from "@rangojs/router";
+import { FlashMessage } from "../location-states";
+
+export async function login(_prev: unknown, formData: FormData) {
+  const email = formData.get("email") as string;
+  const session = await authenticate(email);
+  if (!session) return { error: "Invalid credentials" };
+
+  cookies().set("session", session.token, { httpOnly: true, path: "/" });
+  throw redirect("/dashboard", {
+    state: FlashMessage({ text: "Welcome back!" }),
+  });
+}
+```
+
+Redirects from actions render the **target** route tree's matched segments
+(paths, layouts, parallels, intercepts) and re-resolve its loaders, not the
+source page's — the target is what the user sees next. See `/hooks
+useLocationState` for reading flash state on the target page.
+
+## Error Handling
+
+### Validation errors — return them as state
+
+Recoverable errors (form validation, business rules) should be returned via
+`useActionState`. The form re-renders with the error and the user can fix
+it. Throwing for a validation error escalates to an error boundary, which
+is usually too aggressive.
+
+### Unexpected errors — let them throw
+
+Throw for genuinely exceptional conditions (network failure, DB outage,
+auth violation). The nearest `errorBoundary()` in the route tree catches
+them.
+
+```typescript
+import { errorBoundary } from "@rangojs/router";
+
+layout(CheckoutLayout, () => [
+  errorBoundary(({ error, reset }) => (
+    <div>
+      <p>Checkout failed: {error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )),
+  path("/checkout", CheckoutPage, { name: "checkout" }),
+]);
+```
+
+### Not found from an action
+
+```typescript
+import { notFound } from "@rangojs/router";
+
+export async function deletePost(id: string): Promise<void> {
+  "use server";
+  const post = await db.posts.find(id);
+  if (!post) notFound("Post not found"); // hits notFoundBoundary
+  await db.posts.delete(id);
+}
+```
+
+### Authorization in actions
+
+Route middleware does **not** wrap action execution — only global
+middleware (`router.use()`) does. Auth checks must therefore live in
+`router.use()` or inside the action itself. Don't rely on a route-level
+`middleware()` to gate action access.
+
+```typescript
+// router.tsx — global guard wraps action + render
+const router = createRouter()
+  .use(authInit)
+  .use("/admin/*", requireAdmin) // protects actions on /admin too
+  .routes(urlpatterns);
+```
+
+```typescript
+// Or check inside the action body
+"use server";
+import { getRequestContext, redirect, notFound } from "@rangojs/router";
+
+export class ForbiddenError extends Error {
+  constructor() {
+    super("You do not have permission to perform this action.");
+    this.name = "ForbiddenError";
+  }
+}
+
+export async function deleteOrder(orderId: string) {
+  const ctx = getRequestContext();
+  const user = ctx.get("user");
+  if (!user) throw redirect("/login"); // unauthenticated → bounce to login
+
+  const order = await db.orders.get(orderId);
+  if (!order) notFound("Order not found"); // → notFoundBoundary
+  if (order.userId !== user.id) throw new ForbiddenError(); // → errorBoundary
+
+  await db.orders.delete(orderId);
+}
+```
+
+> **Don't `throw new Response("Unauthorized", { status: 401 })`** — non-redirect
+> Responses thrown from actions are treated as errors and routed to the nearest
+> `errorBoundary()`, not returned as real HTTP responses (the dev build warns
+> when you do this). Use `redirect()` to send unauthenticated users to a login
+> page, `notFound()` for missing resources, and a domain error class for
+> forbidden access so the boundary can render an appropriate UI. For
+> recoverable cases, return `{ error: "..." }` via `useActionState` instead of
+> throwing.
+
+## Action Context
+
+Actions can read the request context with `getRequestContext()`. This gives
+the same context-variable, header, and reverse APIs that handlers and
+middleware use.
+
+```typescript
+"use server";
+import { getRequestContext, cookies, headers } from "@rangojs/router";
+
+export async function trackEvent(name: string) {
+  const ctx = getRequestContext();
+  const user = ctx.get("user"); // set by global middleware
+  const ua = headers().get("user-agent");
+  const url = ctx.reverse("dashboard"); // type-safe URL by route name
+  await analytics.record({ name, userId: user?.id, ua, url });
+}
+```
+
+State written via `ctx.set(...)` or `cookies().set(...)` during an action
+is visible to downstream route middleware, segment handlers (path/layout/
+parallel/intercept), loaders, and `revalidate()` callbacks during the
+post-action revalidation render — actions and revalidation share the same
+request scope.
+
+### Constraints
+
+| Constraint                                               | Why                                                                                                                                                                                                                     |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions cannot return or throw a non-redirect `Response` | Return values go through RSC Flight serialization. A thrown non-redirect `Response` is treated as a regular error and hits the nearest `errorBoundary()` (dev warns). Use `redirect()`, `notFound()`, or domain errors. |
+| Route DSL `middleware()` does not wrap actions           | Actions execute before route middleware. Only global `router.use()` middleware (and its scoped variants) wrap action execution.                                                                                         |
+| `useFetchLoader()` is for reads, not writes              | Actions are the mutation primitive; loaders are for data fetching.                                                                                                                                                      |
+
+Cookies/headers set in **global** `router.use()` middleware DO propagate to
+action responses (the same merge path as a normal render). The constraint
+specific to **per-fetchable-loader** middleware (`createLoader(fn, {
+middleware })` on a POST request) is that it cannot set cookies — set them
+in the loader body instead. See `/middleware` for the full middleware
+contract.
+
+## File Uploads
+
+Forms with `enctype="multipart/form-data"` (or any file input) submit to
+actions as `FormData`. Stream the file directly — don't buffer if the
+runtime supports streaming.
+
+Write the action with the `(prevState, formData) => newState` signature so
+it can be passed straight to `<form action={uploadAvatar}>` (PE-compatible)
+**and** to `useActionState` without a client-side wrapper:
+
+```typescript
+// app/actions/avatar.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+
+export type AvatarUploadState = { url?: string; error?: string } | null;
+
+export async function uploadAvatar(
+  _prev: AvatarUploadState,
+  formData: FormData,
+): Promise<AvatarUploadState> {
+  const file = formData.get("avatar") as File | null;
+  if (!file || file.size === 0) return { error: "No file selected" };
+  if (file.size > 5_000_000) return { error: "File too large (max 5MB)" };
+
+  const ctx = getRequestContext();
+  const key = `avatars/${crypto.randomUUID()}-${file.name}`;
+  await ctx.env.BUCKET.put(key, file.stream());
+  return { url: `/r2/${key}` };
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { uploadAvatar, type AvatarUploadState } from "../actions/avatar";
+
+export function AvatarUpload() {
+  const [state, action, pending] = useActionState<AvatarUploadState, FormData>(
+    uploadAvatar,
+    null,
+  );
+  return (
+    <form action={action}>
+      <input type="file" name="avatar" accept="image/*" />
+      <button disabled={pending}>{pending ? "Uploading…" : "Upload"}</button>
+      {state?.error && <p role="alert">{state.error}</p>}
+      {state?.url && <img src={state.url} alt="" />}
+    </form>
+  );
+}
+```
+
+Wrapping the action in a client-side inline function (`useActionState(async
+(_prev, fd) => uploadAvatar(fd), null)`) breaks PE: that closure isn't a
+server reference, so the form has no real `action` URL when JS hasn't
+loaded. Keep the action's signature `(_prev, formData)` and pass it
+directly.
+
+For client-side upload progress or cancellation, use a fetchable loader
+with `useFetchLoader()` instead — see `/hooks useFetchLoader`.
+
+## Tracking Action State Without `useActionState`
+
+Use `useAction()` from `@rangojs/router/client` to track an action's
+state from outside a form (e.g. an action triggered by `onClick`).
+
+```tsx
+"use client";
+import { useAction } from "@rangojs/router/client";
+import { addToCart } from "../actions/cart";
+
+function AddButton({ productId }: { productId: string }) {
+  const { state, error } = useAction(addToCart);
+  return (
+    <>
+      <button
+        onClick={() => addToCart(productId)}
+        disabled={state === "loading"}
+      >
+        {state === "loading" ? "Adding…" : "Add"}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  );
+}
+```
+
+`useActionState` and `useAction` are complementary — use `useActionState`
+for `<form action={...}>` flows, `useAction` for imperative button clicks
+or to observe an action triggered elsewhere on the page.
+
+## Progressive Enhancement
+
+`<form action={serverAction}>` works without JavaScript: the form posts as a
+normal HTTP request, the action runs, and the page re-renders server-side.
+For PE to work, write actions that accept `FormData` directly (not curried
+or wrapped):
+
+```tsx
+// Works with no-JS submission
+<form action={submitName}>
+  <input name="name" />
+  <button>Submit</button>
+</form>
+```
+
+```typescript
+"use server";
+export async function submitName(formData: FormData) {
+  const name = formData.get("name") as string;
+  await db.entries.add({ name });
+}
+```
+
+`useActionState` and `useOptimistic` only enhance the experience once JS is
+loaded — without JS, the underlying action still runs and the page still
+re-renders. Don't rely on client-only state for required form behavior.
+
+## Cross-references
+
+- `/hooks` — `useAction`, `useFetchLoader`, `useLocationState` (flash state)
+- `/loader` — read patterns, fetchable loaders, revalidation rule semantics
+- `/middleware` — action vs render scope, revalidation contracts
+- `/links` — `ctx.reverse()` and `getRequestContext().reverse()` from actions
+- `/migrate-react-router` — `action()` → `"use server"` mapping
+- `/migrate-nextjs` — Next.js server action parity