# Tutorials

Tutorials are for **learning by building**. Each one walks a fixed path from an empty directory to a running application — no step skipped, every rung proven by a real command or endpoint. You don't need to understand the whole framework before you start; each track introduces its capabilities in the order you'd actually reach for them.

Unlike the [how-to guides](https://rickylabs.github.io/netscript/how-to/), which assume you already know the shape of the task, a tutorial follows one continuous example and never leaves you guessing what to do next.

> How the four lanes fit together
>
> Tutorials teach you a path end to end. When you already know the path and just need the recipe, use the
>
> how-to guides
>
> . For exact symbols and signatures, go to the
>
> reference
>
> . For the design reasoning behind durability, contracts, and plugins, read the
>
> explanation
>
> pages.

## Five tracks, five applications

There are five independent tracks. **Each builds one complete application** from a fresh `netscript init`, and each ends by running that application **locally under .NET Aspire** — so whichever you pick, you finish with something that boots, serves, and survives a restart. The tracks don't depend on each other; start with the one closest to what you're building.

[Storefront  Build an e-commerce backend: a typed catalog service, contract-first cart, a durable `checkout` saga with compensation, and an HMAC-verified shipping webhook. The track for **services + durable workflows**. 7 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/)

[Team Workspace  Build an authenticated SaaS backend: add a pluggable auth backend and session, model per-plugin data across a second database, run a provisioning job, and protect routes with the `.withAuthz()` seam. The track for **auth + access control**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/)

[ERP Sync  Build a legacy-ERP migration sync: watch for incoming data files, ingest them with durable jobs, run a sandboxed transform task, and add a queue provider and a cron schedule. The track for **jobs, queues & polyglot**. 5 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/)

[Live Dashboard  Build a real-time UI that stays current with no polling and no hand-rolled WebSocket: go from a typed contract to an SDK client, a cache-first query, a Fresh `definePage` with a hydrated `QueryIsland`, and finally a durable StreamDB feed that pushes updates into the table live. The track for **the typed-end-to-end Fresh + SDK stack**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

[AI Chat  Build a durable AI chat app whose transcript, streaming markdown, tool-call cards, and MCP widgets survive reload and reconnect: wire a durable chat route on `@netscript/fresh/ai`, hydrate the `fresh-ui` chat components, add a server-side tool, connect a remote MCP server, and turn the island live. The track for **durable AI chat**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/)

## Not sure which to pick?

**Choose by what you're building**

| Name | Type | Description |
| --- | --- | --- |
| `An API with multi-step business logic` | `Storefront` | You need typed services and a workflow that can't half-complete — orders, payments, fulfillment. Teaches contracts, defineService, sagas, and webhooks. |
| `An app behind a login` | `Team Workspace` | You need authentication, sessions, and route-level access control before anything else. Teaches the auth backend, session crypto, and the .withAuthz() seam. |
| `Data pipelines and scheduled work` | `ERP Sync` | Your work happens off the request path — file ingestion, batch jobs, scheduled syncs, and tasks in other languages. Teaches triggers, jobs, queues, cron, and the task runtime. |
| `A live, reactive frontend` | `Live Dashboard` | You're rendering server data in a Fresh UI that stays current without a refresh. Teaches the SDK client, cache-first queries, the page builder, islands, and durable streams. |
| `A durable AI chat app` | `AI Chat` | You're building a chat UI whose transcript, streaming markdown, tool-call cards, and MCP widgets survive reload and reconnect, with replies that stream in live. Teaches the durable chat route on @netscript/fresh/ai, the fresh-ui chat components, a server-side tool, the MCP client stack, and the live subscription. |

New to NetScript entirely? Any track starts from zero, but **Storefront** is the broadest tour of the core ideas — to inspect the whole shape of a NetScript backend, start there.

## Before you start

Every track assumes a working local toolchain. If you have never run NetScript on this machine, the [quickstart](https://rickylabs.github.io/netscript/quickstart/) installs the CLI and gets a project up in a few commands; each track's first chapter then re-grounds you from the scaffold, so you can start in either place.

> What you'll need
>
> A recent
>
> Deno
>
> and the
>
> .NET Aspire
>
> CLI on your PATH. Install the NetScript CLI with
>
> deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.6
>
> . Each chapter lists its own prerequisite state, so you always know which earlier chapters it builds on.

## When you finish

Once you've completed a track, branch out into the rest of the docs:

[How-to guides  Task-focused recipes for things the tutorials don't cover — discovering services, exposing OpenAPI, choosing a queue provider, second databases, and production pitfalls.](https://rickylabs.github.io/netscript/netscript/how-to/)

[Capabilities  One hub per capability (services, workers, sagas, triggers, streams, auth) with the headline API, ports, and endpoints on one screen.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Reference  Generated, always-current API surface for every `@netscript/*` unit — exact symbols, signatures, and types.](https://rickylabs.github.io/netscript/netscript/reference/)

[Explanation  The design reasoning behind contracts-first services, durable execution, the plugin model, and the local Aspire topology.](https://rickylabs.github.io/netscript/netscript/explanation/)