# All recipes

Recipes live inside their pillar in the sidebar — each area's **Recipes** section sits below the guides that teach the basics it assumes. This page is the cross-area index: every recipe in the docs, grouped by pillar, so you can scan the whole catalog in one place. Each one is goal-first — it starts from a concrete intent and ends with a command that proves the change works.

> One prerequisite spans almost every recipe
>
> Anything that touches Postgres, Redis/Garnet, or a plugin service expects Aspire to be running first. From your workspace:
>
> cd aspire && aspire start
>
> brings up the dependencies and the dashboard on
>
> `https://localhost:18888`
>
> before
>
> any
>
> netscript db
>
> command or service call. The recipes call this out where it matters, but it is the single most common missing step.

## Preferred NetScript paths

Start with the framework-owned path below. The lower-level alternatives remain useful when you need to integrate an existing host, but they should not be the first construction you copy into a NetScript workspace.

| Task | Preferred path | Why this path comes first |
| --- | --- | --- |
| Load data for a typed page | [`definePage().withResource(...)`](https://rickylabs.github.io/netscript/web-layer/builders/) | Keeps route data in the page builder instead of recreating an Express-style loader. |
| Keep island data live | [`useLiveQuery`](https://rickylabs.github.io/netscript/web-layer/query/) | Uses the package-owned query bridge, hydration, and cleanup rather than a hand-rolled polling loop. |
| Add or customize UI | [`netscript ui:add`](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) | Copies registry source and its token-driven styles into the app you own. |
| Deploy to Google Cloud | [`netscript deploy cloud-run`](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/) | Uses the first-class target lifecycle (`plan`, `up`, `down`) instead of an unrelated deployment wrapper. |
| Back TanStack DB with a service | [`@netscript/sdk/collections`](https://rickylabs.github.io/netscript/reference/sdk/#collections-netscriptsdkcollections) | Builds the collection from the typed service/query surface. |
| Connect a typed client to TanStack Query | [`@netscript/sdk/query-client`](https://rickylabs.github.io/netscript/services-sdk/sdk/#service-discovery-query-client) | Supplies NetScript query keys, invalidation, persistence, and service utilities. |
| Add server-side stale-while-revalidate caching | [`CacheQuery` from `@netscript/sdk/cache`](https://rickylabs.github.io/netscript/reference/sdk/) | Uses the SDK cache engine and its provider boundary rather than a parallel cache contract. |
| Publish interactive API documentation | [Scalar/OpenAPI](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/) | One service option exposes the contract-derived spec and the bundled Scalar UI. |

The linked recipe or guide is the canonical sample. When it also shows a general-purpose construction, that alternative is an integration escape hatch, not the default NetScript route.

## Web Layer

- [Customize the Fresh UI](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) — bring the dashboard components into your workspace with `ui:init` / `ui:add` and edit them directly.
- [Build a server-validated form](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/) — route-bound form state, server validation, mutation, and success handling in one typed page definition with `definePage().withForm()`.
- [Build a desktop frontend](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-desktop-frontend/) — one Fresh frontend that runs as an ordinary browser app and gains native capabilities on the desktop.

## Services & SDK

- [Add a service](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/add-a-service/) — run `netscript service add --name <service> --with-client` to define a typed contract, generate `apps/<app>/lib/<service>.ts`, implement the handlers, and confirm the service answers on `/api/rpc/*`.
- [Discover services](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/) — call another plugin's or workspace member's typed service without hardcoding its address.
- [Expose OpenAPI & Scalar](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/) — publish an OpenAPI document and browsable Scalar docs for a service.

## Background jobs

- [Run a polyglot task](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/) — define a non-TypeScript script (Python, shell, .NET, any executable) as a task with a permission sandbox and run it through the executor.
- [Tune the worker runtime](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/) — trade throughput against isolation with concurrency, runner mode, per-task permissions, and timeouts/retries.
- [Restrict worker task permissions](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/restrict-worker-task-permissions/) — give every Deno task explicit permissions; an omitted permission object compiles to `--allow-all`.
- [Add a task runtime adapter](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/add-a-task-runtime-adapter/) — advanced: add a custom runtime adapter to the built-in task executor.

## Durable workflows

- [Build a validated ingestion queue](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/) — a typed queue whose messages are schema-checked before they enter the queue and again before a consumer handles them.
- [Publish a durable stream](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/publish-a-durable-stream/) — let server-side state be subscribed to by browsers and other consumers through a durable stream service.

## AI & Agents

- [Build a durable chat](https://rickylabs.github.io/netscript/netscript/ai/how-to/build-a-durable-chat/) — an AI chat on a Fresh route whose transcript survives reload and reconnect, with one server-side tool.

## Data & Persistence

- [Database & migration](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) — initialize, generate, seed, and inspect the Postgres schema with the `netscript db` commands.
- [Queue / KV / cron](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/queue-kv-cron/) — the reactive KV store, the durable queue, and cron schedules, including `--unstable-kv`.
- [Choose a queue provider](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/) — pick the right queue backend, and either let auto-discovery select one or pin one explicitly.
- [Use a second database](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/) — add a second Postgres, or a MySQL/SQL Server instance, alongside the default database.

## Identity & Access

- [Add authentication](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/) — install the official auth plugin, pick one active backend via `NETSCRIPT_AUTH_BACKEND`, migrate, and sign in.

## Orchestration & Runtime

- [Add a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) — install a first-party plugin, regenerate the registry, and verify the service answers.
- [Deploy locally with Aspire](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/) — run the full local resource graph from the generated Aspire AppHost.
- [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/) — the portability story: raw `deno task` entry points and the `--no-aspire` escape hatch when you provision dependencies yourself.
- [Deploy to Deno Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-deno-deploy/) — push a preview, promote to prod, and read status and logs with the first-class deploy command.
- [Graceful shutdown](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/) — drain in-flight requests and jobs, run teardown hooks, and close connections on `SIGINT`/`SIGTERM`.
- [Roll out runtime overrides](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/) — change a deployed behavior without rebuilding the workspace.
- [Author a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/author-a-plugin/) — advanced: build a custom plugin with the same manifest and `mod.ts` contract the first-party plugins use.
- [Deno LSP code intelligence](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deno-lsp-code-intelligence/) — keep go-to-definition, hover, and diagnostics aligned across CLI and editors.

## Observability

- [Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/) — emit custom spans and structured logs, propagate `traceparent`, and read the traces in the Aspire dashboard.

---

Not sure which recipe you want? Name the outcome first. *"Users must sign in"* → [Add authentication](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/). *"This event should fan out to a background job"* → [Add a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/). *"It has to run where there is no Aspire"* → [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/). The recipes are deliberately small and composable; most real features chain two or three of them.