Scaffold the workspace

This is the first chapter of the ERP Sync track. Before you can watch files or run background jobs, you need a workspace with the right plugins installed and an orchestrator to run them. In this chapter you create my-erp/, add the workers and triggers plugins, and boot the whole stack under Aspire so the rest of the track has something real to build on.

What you will build

By the end of this chapter you will have my-erp/ on disk — a NetScript workspace with a Postgres database, the workers plugin at plugins/workers/ (the background-job engine on :8091), and the triggers plugin at plugins/triggers/ (the ingress engine on :8093) — all running together under one aspire start, with the Aspire dashboard live on :18888.

Before you begin

You need the same local toolchain the main tutorials use:

Deno 2.x on your PATH — check with deno --version.
The Aspire CLI — check with aspire --version. Aspire provisions your database and cache locally so you do not wire up Docker by hand.
Docker running, so Aspire can start the Postgres and Redis containers — confirm with docker info.

Install the NetScript CLI from JSR once, then confirm it:

deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-alpha.12
netscript --help

You should see the public command groups, including init, plugin, generate, db, and deploy. If netscript is not found, make sure Deno's install directory is on your PATH and open a fresh terminal.

Step 1 — Preview the scaffold with a dry run

Before writing files, ask the CLI what it would create. --dry-run plans the scaffold and prints the file and directory totals per phase without touching disk:

netscript init my-erp --dry-run

A clean dry run means your flag combination is valid — the CLI rejects bad option mixes (an unknown --db engine, for instance) here, before any files exist. Treat it as a green light to scaffold for real.

Step 2 — Create the workspace

This track needs a database to anchor durable execution, so scaffold with Postgres — the recommended default. --db is polyglot: swap postgres for mysql, mssql, or sqlite and the rest of the track works the same (this track uses postgres throughout):

netscript init my-erp --db postgres
cd my-erp

This scaffolds my-erp/, formats the output with deno fmt, and initializes a git repository. On completion the CLI prints a next steps summary tailored to your options.

netscript init options used here (run netscript init --help for the full list)
Option	What it does
--db postgres	Scaffold a Postgres database workspace. Durable execution and queue persistence anchor on it.
--dry-run	Plan the scaffold and print totals without writing any files.
--no-aspire	Skip the Aspire orchestration files. Do NOT pass this — the rest of the track runs under Aspire.

Step 3 — Add the workers plugin

NetScript's background capabilities arrive as plugins. Add the workers plugin with its sample jobs so you have a working reference to read and adapt:

deno run -A packages/cli/bin/netscript-dev.ts plugin add worker --name workers --samples

This lands the plugin at plugins/workers/ — the canonical, config-referenced install location — and registers it in netscript.config.ts (./plugins/workers/mod.ts) and appsettings.json. The workers plugin ships an API service on :8091 and a separate background processor that drains the job queue.

Step 4 — Add the triggers plugin

Now add the triggers plugin, which is how NetScript receives events — including the file-watch trigger you build in Chapter 2:

deno run -A packages/cli/bin/netscript-dev.ts plugin add trigger --name triggers --samples

This lands a workspace at plugins/triggers/ and registers it in netscript.config.ts (./plugins/triggers/mod.ts) and appsettings.json. The triggers API runs on :8093. Confirm both plugins registered:

netscript plugin list

You should see workers and triggers in the registry.

Step 5 — Bring up orchestration

This is the step that turns a folder of files into a running system. Aspire provisions your database and cache and starts every process; you do not start containers by hand, and you run it before any netscript db command. Run it from the aspire/ subfolder so the CLI sees apphost.mts:

cd aspire
aspire restore   # once per machine: restores the Aspire SDK modules into .aspire/
aspire start       # starts the AppHost and every declared resource

aspire start brings up Postgres, the Redis cache, the workers API + processor, and the triggers API

processor together, then prints a URL and a one-time login token for the Aspire dashboard:

http://localhost:18888

The dashboard's Resources tab is the authority for which port each resource bound — the conventional assignments (workers :8091, triggers :8093) are what this two-plugin workspace lands on, allocated from the :8091–8099 plugin range. Leave aspire start going in this terminal; it is your control plane for the rest of the track.

Verify your progress

In a second terminal (leave aspire start going in the first), confirm both plugin APIs are alive:

curl http://localhost:8091/health   # workers API
curl http://localhost:8093/health   # triggers API

Both should return a healthy JSON response. Then type-check the whole workspace from the project root:

deno task check

Expected: a clean check with no errors — the scaffold, both plugins, and the database wiring all line up.

[ ] my-erp/ exists with plugins/workers/ and plugins/triggers/ on disk.
[ ] netscript plugin list shows both workers and triggers.
[ ] aspire start is up; the dashboard on :18888 lists postgres, redis, and both plugin APIs.
[ ] curl :8091/health and curl :8093/health both return healthy.
[ ] deno task check is clean.

What you built

A real NetScript workspace, my-erp/, with the workers and triggers plugins installed and the whole stack — Postgres, Redis, both plugin APIs and their background processors — running under one aspire start and visible in the dashboard. Next, you give it something to do.