Build a storefront backend

This track is a project, not a tour. Across seven chapters you build a small e-commerce storefront — a products catalog, a cart, a durable checkout, a shipping webhook, and a storefront page — in one workspace that grows chapter by chapter. It is the same spine the NetScript playground runs, re-themed as a shop, so every pattern you learn here is one the framework's own example app uses in anger.

The differentiator this track proves is one typed contract, honored from the database to the button: the oRPC schema you write once is the same object the server handler validates against, the same one a page's query and checkout mutation are typed from, so a wrong field is a compile error, not a 2 a.m. incident. What this replaces: the hand-maintained REST-plus-fetch-wrapper-plus-DTO stack where the client's idea of a cart and the server's idea of a cart are two files that drift until production catches them apart.

What you will build

A working storefront backend called my-shop/: a typed products catalog service backed by Postgres, a cart domain defined contract-first, a durable checkout saga that survives restarts and compensates on failure, and an HMAC-verified shipping webhook that hands inbound provider events to a background job. By the last chapter the whole thing runs on your machine under one orchestrator, visible in a single dashboard.

The arc is deliberate. It teaches NetScript's central opinion — the oRPC contract is the single source of truth — and then shows what that buys you once the happy path needs to survive money changing hands: durable workflows and verified webhooks make checkout reliable instead of hopeful.

The shape of the app

Catalog → cart → checkout → shipping

Products live in a typed service. A cart contract models a new domain. Checkout is a durable saga with a compensation branch. Shipping arrives as a verified webhook that enqueues a job. Each piece is one chapter.

Contract-first, everywhere

Every service surface is an @orpc/contract route with Zod input/output schemas — many of them generated from Prisma. Write the schema once and the server handler, the typed client, and the OpenAPI projection all agree.

Durable by design

Checkout is not a one-shot call — it is a state machine with defineSaga that checkpoints its state, reacts to payment and inventory messages, and runs a compensation path when a step fails.

Who this is for

You are comfortable with TypeScript and have used Deno at least a little. You do not need prior NetScript experience — chapter 1 starts from an empty folder — but if you have never run the framework locally, skim the Quickstart first; it covers the same scaffold at a gentler pace. This track moves faster and stays on the storefront domain the whole way.

You also do not need to read the whole framework before you start. Each chapter introduces exactly one new capability, grounds it in real running code, and proves it with a command whose output you can check.

The seven chapters

1 · Scaffold

Create my-shop/ with the netscript CLI and boot it under Aspire. Postgres (the default; swap --db postgres for mysql, mssql, or sqlite), the Redis cache, and your service come up together; the dashboard answers on :18888.

2 · Catalog service

Define a typed products contract whose schemas come from Prisma, implement the handlers against a Postgres-backed database client, and serve it with defineService (on port 3001 in this tutorial; note that each scaffolded project is allocated its own randomized high-range ports).

3 · Cart contracts

Model a brand-new cart domain contract-first — list, getById, create, update — with shared typed errors, then derive a fully typed client from it. No handler guesswork.

4 · Checkout saga

Turn checkout into a durable workflow with defineSaga: a state machine that walks order → payment → inventory → shipment and compensates when a step fails.

5 · Shipping webhook

Accept an HMAC-verified shipping/payment webhook with defineWebhook and hand each inbound event to a background job with enqueueJob.

6 · Storefront UI

Put a face on the backend: a typed cart route with createRouteReference, a catalog query and a checkout mutation driven through createServiceClient → createQueryFactories in a Fresh island. The typed contract, honored all the way to the button.

7 · Deploy

Run the whole storefront locally under one aspire start — every service, plugin API, and background processor in one resource graph, observable from the dashboard. The local topology, not a cloud deployer.

Start the build

After this track, keep building in Build › Services & SDK — the guides and recipes there pick up where these chapters stop.