Fresh meta-framework

The NetScript Fresh meta-framework is the application layer that turns a route into a typed, server-rendered page. You author a page with definePage() — binding a typed route contract, server resources and layers (each with its own loader, cache window, and partial-refresh endpoint), and forms — then build it into Fresh route wiring. The same contract object a page loader uses to call a service is the one the typed SDK client imports and the oRPC service implements, so the page → contract → SDK → service request model cannot drift.

alpha

What it is

@netscript/fresh is a DSL / builder package over Fresh 2. Its public product is a small set of builders and typed contracts — definePage(), defineRouteContract(), definePartial(), defineFreshApp(), plus form, query, and defer factories — that translate page and route intent into Fresh runtime wiring. A page is composed from three cooperating pieces: a server layer (data resolved by a loader), a partial route that re-renders just that layer on demand, and a hydrated island that shares the same query cache on the client. Rendering is cache-first: a fresh cached payload renders immediately, a stale one renders then reloads in the background (SWR), and a miss falls back to the layer's partial. The contract type-flow that makes this safe end-to-end is explained in Contracts.

Learn → / Do →

Minimal example — an orders page

A page starts with a typed route contract, then definePage() binds it, attaches a metadata resolver, and builds the Fresh route wiring. The search schema below is parsed and type-checked, so ctx.useSearch() inside a loader is fully typed.

// routes/orders/index.tsx
import { definePage } from '@netscript/fresh/builders';
import { defineRouteContract, paginationSearchSchema } from '@netscript/fresh/route';
import { OrdersPanel } from '../../islands/OrdersPanel.tsx';

// 1. The route contract: typed, parsed search params (the single source of truth for this URL).
const ordersRoute = defineRouteContract({
  searchSchema: paginationSearchSchema({
    defaultLimit: 20,
    defaultSort: 'createdAt',
    defaultOrder: 'desc',
  }),
});

// 2. The page: bind the route, load a server resource, render a cache-first layer.
export const ordersPage = definePage()
  .withRoute(ordersRoute)
  .withResource('orders', async (ctx) => {
    const { limit, sort, order } = ctx.useSearch();
    return await ordersClient.list.query({ limit, sort, order });
  })
  .withLayer('list', OrdersPanel, {
    loader: (ctx) => ({ orders: ctx.useResource('orders') }),
    partialName: 'orders-list',
    staleTime: 30_000,
    staleReloadMode: 'background',
  })
  .withMeta(() => ({ title: 'Orders', description: 'Browse the current order queue.' }))
  .build();

The matching partial route re-renders only the orders-list layer when the island asks for fresh data — same loader, same query key, no full-page reload:

// routes/orders/_partials/orders-list.tsx
import { definePartial } from '@netscript/fresh/builders';
import { OrdersPanel } from '../../../islands/OrdersPanel.tsx';

export const ordersListPartial = definePartial({
  name: 'orders-list',
  loader: async (ctx) => ({ orders: await ordersClient.list.query(ctx.search) }),
  component: OrdersPanel,
});

Key types first — the page builder chain

definePage() returns a fluent builder. Each with* step is typed against the accumulated state, so a search-param key, a resource name, or a layer's props are all inferred forward into the loaders and components downstream. Call .build() last; with a bound route it returns a routed definition exposing route, nav, and hooks.

withLayer options — the cache-first slot

A layer is the unit of independent loading and refresh. Its loader produces props, its partial/partialName names the route that re-renders it in isolation, and the cache/policy keys decide when a stale slot reloads. These are the real keys on PageLayerConfig:

withPolicy — the defer policy enum

withPolicy() (and a layer's policy) accepts a named profile or an override object. The full set of named profiles is:

withForm — server-validated forms as a layer

withForm(id, component, config) registers a form as a typed layer: it wires the method handler, CSRF headers, validation, and form metadata in one step. TOutput is inferred from mutate's return type, so redirectTo/onSuccess are typed against your result.

Route contracts, partials, defer & islands

The route contract is the typed boundary of a URL. defineRouteContract({ pathSchema, searchSchema }) produces a contract whose parsed params flow into the page; the @netscript/fresh/route subpath ships the schema builders and link helpers, and @netscript/fresh/defer + @netscript/fresh/query cover deferral and island hydration.

Production notes

Reference →

This hub is intentionally thin — the full generated API for every subpath (server, builders, route, defer, form, query, interactive, streams, vite) lives in the reference.

fresh