Merge pull request #213 from JoviDeCroock/JoviDeCroock/issue-106

Add configurable route loader cache duration

Author: JoviDeCroock

.changeset/loader-cache-duration.md

@@ -0,0 +1,12 @@
+---
+"@pracht/core": patch
+"@pracht/cli": patch
+---
+
+Add an inheritable `loaderCache` route option for controlling how long browsers privately cache successful route-state loader data. Positive durations emit `Cache-Control: private, max-age=<seconds>`, while `false`, `0`, and the default remain `no-store`.
+
+Expose the resolved loader cache policy in `pracht inspect routes --json` and the MCP route graph.
+
+Manual `useRevalidate()` calls bypass route-state browser caching so explicit refreshes and post-mutation reloads still re-run the loader.
+
+Form redirects after state-changing submissions also bypass cached route-state data when reloading the destination route.

docs/ARCHITECTURE.md

@@ -294,12 +294,15 @@ User clicks <a> or calls navigate()
       └─ Import shell module chunk (if applicable)
   → Otherwise, import the route/shell modules only and skip the server fetch
   → Server runs middleware + loader when needed and returns JSON (no HTML rendering)
+    with no-store by default or the route's private loaderCache duration
   → Client updates component tree with new data + loaded modules
   → Update URL via history.pushState
 ```
 
 Module imports are cached so repeated navigations to the same shell skip the import.
 Prefetching (hover/intent/viewport) also warms module chunks alongside route-state data.
+Its bounded 30-second in-memory reuse window is independent of the route-state
+response's browser HTTP cache policy.
 
 This "server-owned navigation" pattern means loaders never run in the browser.
 Secrets in loader code stay server-side. The client only receives serialized data.

docs/DATA_LOADING.md

@@ -70,7 +70,30 @@ plugins turn Markdown/MDX or TypeScript route files into JavaScript.
 
 Framework-generated route-state responses add `Vary: x-pracht-route-state-request`
 so caches keep HTML and JSON variants separate. Those JSON responses also default
-to `Cache-Control: no-store` unless your app sets a stricter policy explicitly.
+to `Cache-Control: no-store`.
+
+Use `loaderCache` in route metadata when loader data can safely be reused by the
+same browser:
+
+```typescript
+route("/settings", () => import("./routes/settings.tsx"), {
+  render: "spa",
+  loaderCache: 3600,
+});
+```
+
+A positive integer sets `Cache-Control: private, max-age=<seconds>` on successful
+route-state data responses. `loaderCache: false` and `loaderCache: 0` both produce
+`no-store`, which also lets a route opt out of a group default. Redirects and error
+responses remain `no-store`. If a loader returns a `Response` with an explicit
+`Cache-Control` header, that header takes precedence over route metadata.
+
+`loaderCache` is client-side browser caching only. It does not change ISG
+`revalidate`, and the prefetcher's bounded 30-second in-memory cache remains
+independent so an intent prefetch can still be consumed by the navigation that
+immediately follows it. Explicit `useRevalidate()` calls bypass this browser
+cache so user-triggered refreshes and post-mutation reloads still re-run the
+loader.
 
 For SPA routes, the initial HTML can still include the matched shell and an
 optional shell `Loading` export so the page is not blank before the route-state

docs/REQUEST_FLOWS.md

@@ -26,7 +26,8 @@ and returns a small JSON envelope:
 
 The `Vary: x-pracht-route-state-request` response header tells caches to keep
 the HTML and JSON variants separate. JSON responses default to
-`Cache-Control: no-store`.
+`Cache-Control: no-store`; a positive route `loaderCache` value changes
+successful loader-data responses to `private, max-age=<seconds>`.
 
 If the target route has neither a loader nor middleware, client navigation can
 skip the route-state request entirely and only load the route/shell modules.
@@ -397,6 +398,10 @@ Vary: x-pracht-route-state-request
 Cache-Control: no-store
 ```
 
+`Cache-Control` above is the default. Routes configured with
+`loaderCache: <seconds>` return `private, max-age=<seconds>` for successful data;
+redirects and errors remain `no-store`.
+
 No HTML is rendered during navigation regardless of the target route's mode.
 The client updates the component tree in-place.
 

docs/ROUTING.md

@@ -93,7 +93,7 @@ Defines a single route:
 | ------ | ----------- | ------------------------------------------------------ |
 | `path` | `string`    | URL pattern (e.g. `/blog/:slug`)                       |
 | `file` | `ModuleRef` | Module reference — `() => import("./path")` or string  |
-| `meta` | `RouteMeta` | Optional: render mode, shell, middleware, revalidation |
+| `meta` | `RouteMeta` | Optional: render mode, shell, middleware, revalidation, loader caching |
 
 > [!IMPORTANT]
 > Function module refs must use the exact inline form `() => import("./path")`
@@ -107,7 +107,7 @@ Groups routes with shared configuration:
 
 | Param    | Type                | Description                                           |
 | -------- | ------------------- | ----------------------------------------------------- |
-| `meta`   | `GroupMeta`         | Shell, middleware, render mode, pathPrefix to inherit |
+| `meta`   | `GroupMeta`         | Shell, middleware, render mode, loader cache, pathPrefix to inherit |
 | `routes` | `RouteDefinition[]` | Routes in this group                                  |
 
 Group properties cascade to children. A route's own meta overrides the group's.
@@ -124,6 +124,7 @@ interface RouteMeta {
   hydration?: "full" | "islands" | "none"; // Partial hydration (see ISLANDS.md)
   middleware?: string[]; // Named middleware from defineApp.middleware
   revalidate?: RouteRevalidate; // ISG revalidation policy
+  loaderCache?: number | false; // Browser cache seconds for route-state loader data
   prefetch?: "none" | "hover" | "viewport" | "intent"; // Route-level prefetch strategy (default: "intent")
   speculation?: "prefetch" | "prerender" | { mode; eagerness };
 }
@@ -134,6 +135,13 @@ interface RouteMeta {
 through `group(...)` like `render` and documented in
 [ISLANDS.md](ISLANDS.md).
 
+`loaderCache` accepts a non-negative integer number of seconds or `false`.
+Positive values set `Cache-Control: private, max-age=<seconds>` on successful
+route-state loader data. `0`, `false`, and an omitted value use `no-store`.
+It inherits through `group(...)`, and a route-level value overrides the group.
+This browser cache is independent of ISG `revalidate` and the client's 30-second
+in-memory prefetch cache. See [DATA_LOADING.md](DATA_LOADING.md#loaders).
+
 See [Speculation Rules](#speculation-rules) for `speculation` semantics and how
 it composes with the JS-based `prefetch` strategy.
 
@@ -263,7 +271,8 @@ and `<Link prefetch>` overrides it per link:
 Prefetching warms the route's JS chunks and caches the route-state JSON in a
 bounded LRU cache (30s TTL); a subsequent navigation consumes the cached
 result instead of fetching again. Failed prefetches are evicted so they never
-poison a later navigation.
+poison a later navigation. This short-lived in-memory cache is independent of
+the route's HTTP `loaderCache` policy.
 
 There is also an imperative API for warming a route from code (e.g. before
 opening a client-side dialog that links somewhere):

e2e/basic.test.ts

@@ -230,6 +230,15 @@ test("route state request returns JSON", async ({ request }) => {
   expect(json.data.highlights).toContain("Hybrid route manifest");
 });
 
+test("route state request uses the configured loader cache duration", async ({ request }) => {
+  const response = await request.get("/pricing", {
+    headers: { "x-pracht-route-state-request": "1" },
+  });
+
+  expect(response.status()).toBe(200);
+  expect(response.headers()["cache-control"]).toBe("private, max-age=60");
+});
+
 // ---------------------------------------------------------------------------
 // 404 handling
 // ---------------------------------------------------------------------------

examples/cloudflare/src/routes.ts

@@ -17,6 +17,7 @@ export const app = defineApp({
       }),
       route("/pricing", () => import("./routes/pricing.tsx"), {
         id: "pricing",
+        loaderCache: 60,
         render: "isg",
         revalidate: timeRevalidate(3600),
         speculation: "prefetch",

examples/docs/src/routes/docs/data-loading.md

@@ -64,6 +64,32 @@ export. Named route exports such as `loader`, `head`, `headers`,
 > [!NOTE]
 > Loaders **never** run in the browser. Database connections, API keys, and secrets in loader code stay server-side permanently.
 
+### Route-state caching
+
+Client navigation fetches loader data through Pracht's route-state endpoint. By
+default those JSON responses use `Cache-Control: no-store`, so every navigation
+asks the server for fresh loader data.
+
+Use `loaderCache` in route metadata when the returned data can safely be reused
+by the same browser for a short time:
+
+```ts [src/routes.ts]
+route("/pricing", "./routes/pricing.tsx", {
+  render: "isg",
+  loaderCache: 60,
+});
+```
+
+A positive value sets `Cache-Control: private, max-age=<seconds>` on successful
+route-state responses. `loaderCache: false` and `loaderCache: 0` keep `no-store`
+and can opt a route out of a group default.
+
+Only cache data that is safe to reuse for the configured duration in the same
+browser. Avoid positive `loaderCache` values for loader data that depends on the
+current user, permissions, session, or cookies. `loaderCache` does not change
+ISG `revalidate`, and it is separate from Pracht's short in-memory prefetch
+cache.
+
 ### Error handling
 
 Throw `PrachtHttpError` for structured error responses. Pair it with an `ErrorBoundary` export to render a fallback UI:
@@ -258,6 +284,10 @@ export function Component() {
 }
 ```
 
+Manual revalidation bypasses route-state browser caching, including
+`loaderCache`, so refresh buttons and post-mutation reloads fetch fresh loader
+data.
+
 ### useNavigation()
 
 Reactive pending state for the current navigation or `<Form>` submission — the

packages/cli/src/app-graph.ts

@@ -10,6 +10,7 @@ const METHOD_ORDER: HttpMethod[] = [...HTTP_METHODS];
 export interface AppGraphRoute {
   file: string;
   id: string;
+  loaderCache: number | false | null;
   loaderFile: string | null;
   middleware: string[];
   path: string;
@@ -33,6 +34,7 @@ export interface AppGraph {
 interface ResolvedRouteEntry {
   file: string;
   id: string;
+  loaderCache?: number | false;
   loaderFile?: string;
   middleware: string[];
   path: string;
@@ -67,6 +69,7 @@ export function serializeResolvedRoutes(routes: ResolvedRouteEntry[]): AppGraphR
   return routes.map((route) => ({
     file: route.file,
     id: route.id,
+    loaderCache: route.loaderCache ?? null,
     loaderFile: route.loaderFile ?? null,
     middleware: route.middleware,
     path: route.path,

packages/cli/test/mcp-server.test.ts

@@ -173,6 +173,7 @@ export const app = defineApp({
         {
           file: "./routes/dashboard.tsx",
           id: "dashboard",
+          loaderCache: null,
           loaderFile: null,
           middleware: [],
           path: "/dashboard",