Web Rendering and Routes

Requirement A route's loader MUST prefetch each read it needs through the query cache before the component runs.

Rationale The page then renders with its data rather than showing a spinner after it has already appeared. The cache owns freshness. The router never holds a second copy. This realizes litespec/frontend/rendering#load-route-data-before-rendering.

Example An entity route prefetches its record and every read the record's own sections need.

loader: async ({ context, params }) => {
  const order = await context.queryClient.ensureQueryData(orderQuery(params.orderId));

  if (order.merchantId !== null) {
    await context.queryClient.ensureQueryData(merchantQuery(order.merchantId));
  }
}

The Svelte load does the same:

export async function load({ parent, params }) {
  const { queryClient } = await parent();
  const order = await queryClient.ensureQueryData(orderQuery(params.orderId));

  if (order.merchantId !== null) {
    await queryClient.ensureQueryData(merchantQuery(order.merchantId));
  }

  return { orderId: params.orderId };
}

Requirement A component MUST read route data with a suspense query over the same cache key its loader filled.

Rationale A read naming another key issues a second request. The two answers can disagree. A failed read reaches the route's error boundary, which draws the shared problem state. This realizes litespec/frontend/rendering#read-route-data-from-the-route-cache.

Example

React:

const { data: order } = useSuspenseQuery(orderQuery(orderId));

Svelte:

const order = createQuery(() => orderQuery(orderId));

Requirement A route MUST declare its search parameters in a validated schema, including its filters and its page.

Rationale A filtered list is then a link somebody can share, bookmark, and reopen. A filter in component state reaches nobody. It is lost on the first navigation away. This realizes litespec/frontend/rendering#keep-address-parameters-validated-by-a-schema.

Example The list schema declares its own text field and spreads the shared paging fields.

validateSearch: z.object({ q: z.string().trim().catch("").default(""), ...pagingSearch }),

The Svelte page parses the same shape from the address:

const search = orderSearch.parse(Object.fromEntries(url.searchParams));

Requirement A frontend MUST load each route and each language as its own chunk, with no icon set or language imported whole.

Rationale A signed-in user opens one address and reads one language. A reader in Dutch who never leaves the dashboard should not download English. This realizes litespec/frontend/rendering#load-each-route-and-each-language-separately.

Example loadDictionary returns a dynamic import of one language. The React router plugin splits each route file, and SvelteKit splits each route folder.

Requirement A frontend MUST prefetch the route a pointer is over, and never treat that prefetch as a cache beyond the query cache.

Rationale Most navigations then render from the cache the loaders already filled. A router caching a second time serves a stale answer beside a fresh one. This realizes litespec/frontend/rendering#prefetch-a-route-on-intent.

Requirement A public route MUST define its title, its description, its canonical address, and its indexing policy, while a private route refuses indexing.

Rationale The metadata is what a search result and a shared link show. An indexed console exposes an address a signed-in user believes is private.

Example A channel route states og:* tags and one alternate per language. A console route ships a noindex meta tag in its document.

Requirement Actor-specific data MUST declare its cache key, partition, invalidation owner, and security review before caching, beside the query definition setting the key.

Rationale Shared route or loader behavior otherwise serves one actor's data to another. An uncached read is the safe default. A cache partitioned per request is the safe server shape. This realizes litespec/frontend/rendering#keep-authenticated-caching-explicit.

Requirement A development or edge proxy rule MUST route only, and never decide who the actor is or what the actor may read.

Rationale The proxy runs before the request reaches the API. It cannot see the resource authorization depends on. Forwarding the API's own paths gives the browser one origin. That makes an HTTP-only session cookie a first-party cookie of the page. This realizes litespec/frontend/rendering#keep-proxy-behavior-at-the-edge.

Example A development proxy forwards /api and /auth to the API and changes nothing else.

Requirement A server-rendered frontend MUST construct its query cache inside each request.

Rationale Two readers served at the same time must not read each other's data. A cache outliving one request would serve the next reader the previous reader's answer. This realizes litespec/frontend/rendering#build-the-server-data-cache-per-request.