Add a plugin

Goal: add one of NetScript's official plugins — workers, sagas, triggers, streams, or auth — to an existing workspace, register it with the runtime, and confirm it is wired up and healthy.

This is a task-oriented recipe. It assumes you already have a NetScript workspace (created with netscript init) and that the netscript command is on your path. Each step is a single command you run from your workspace root; the Verify step proves the plugin landed before you write a line of application code. For the exact APIs each plugin exposes, follow the reference links at the end — this guide adds the plugin; the reference documents its surface.

Before you start

You need:

• An existing NetScript workspace. If you do not have one yet, create it first with netscript init — walk through the Quickstart or the tutorials index.
• The netscript command on your path. Run netscript --help to confirm it resolves, and netscript plugin --help for the exact option spelling in your installed version. If the command is missing, install it:

deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.8

netscript --help
netscript plugin --help

• Aspire up if you plan to run the plugin. Adding and registering a plugin is offline, but several plugins (workers, sagas, auth) need a database and Redis to actually run. The database is Postgres, the recommended engine (or mysql / mssql / sqlite, chosen at scaffold time with --db). Bring the local stack up first — cd aspire && aspire start — exactly as in Run the stack with Aspire. You do not need it up just to scaffold and register.

Step 1 — Choose the plugin kind

Each official plugin has a kind you pass to the command and a conventional installed name. Use the conventional name unless you have a specific reason to differ — generated registries, ports, and docs all assume it.

Pick the kind for the capability you need:

• workers — background job scheduling, task execution, and worker API endpoints. Fully traced through Aspire (scheduler → queue → worker → subprocess). See Background jobs.
• sagas — durable saga orchestration and long-running workflow APIs, with a selectable durable store (kv or prisma). See Durable sagas.
• triggers — trigger ingress, scheduling, and file watching over raw Hono routes. See Triggers.
• auth — an oRPC auth service (sign-in, callback, sign-out, session, me) backed by a single selectable backend (kv-oauth, WorkOS, or better-auth). See Authentication.
• streams — durable, change-data stream producers served as their own Aspire service. See Streams.

Step 2 — Add the plugin

In the public netscript CLI, plugin install accepts either an official bare alias (workers, sagas, triggers, auth, streams) or a published plugin package specifier such as @netscript/plugin-workers. Add an official plugin by alias:

netscript plugin install workers --name workers

Repeat with the matching alias for the other plugins: sagas, triggers, auth, and streams. The package-spec forms also work, for example netscript plugin install @netscript/plugin-workers --name workers or an explicit jsr: specifier. Run netscript plugin install --help for the version-accurate surface.

Useful options

Run netscript plugin install --help for the full, version-accurate list. The public netscript plugin install command takes the plugin alias or package specifier and applies the workspace-level install flags before invoking the plugin-owned scaffolder:

KV-only installs and projection migration

Install workers, sagas, or triggers with --no-db --no-samples to skip Prisma schema and migration contributions and emit RequiresDb: false for both the API and background processor. The processes still require KV. Their background work runs independently of the web app.

Saga query storage is selected separately with sagas.projection.backend (kv, prisma, or none). In appsettings.json, put Sagas.Projection.Backend on both the saga API entry in NetScript.Plugins and the saga runner entry in NetScript.BackgroundProcessors. Generated helpers forward the selector as NETSCRIPT_SAGA_PROJECTION; that environment value takes precedence over settings. kv writes the KV query model, prisma writes the Prisma query model, and none disables both the instance query projection and durable saga-stream hydration while canonical saga state remains durable. An explicitly selected prisma projection requires the host's saga Prisma delegates; the API fails before listening and the runner fails before starting delivery if those delegates are missing. With kv, retention.archiveToDb: true remains an explicit database archive opt-in for the configured saga group: the runner requests a host Prisma client and archives that group's instances while retaining KV queries. The default archiveToDb: false keeps KV-only installs DB-free. none also disables database archival.

Migration in 0.0.8: re-run each plugin install with --no-db --no-samples --force and regenerate helpers to correct existing DB-dependent metadata. Preserve your user-owned configuration and samples when applying the generated changes. For existing saga entries without a projection selector, the query backend follows Sagas.Store.Backend (or NETSCRIPT_SAGA_STORE), defaulting to KV when neither is set. Select prisma explicitly when relational query storage is required; select kv on both entries when using --no-db. New saga installs default the projection to the selected store backend, which defaults to KV. A DB-enabled install can use KV queries: database availability alone does not imply that the host Prisma client contains saga models. To use a Prisma projection, provision the saga models and regenerate the host client before selecting prisma on both entries.

These install and runner paths have focused tests. The complete KV-only generated runtime across workers, sagas, and triggers is a separate release acceptance gate.

Step 3 — Generate registries and wire the database

After adding plugins, regenerate the plugin registries so the runtime can discover them:

netscript generate plugins

If a plugin contributes runtime configuration schemas, also run:

netscript generate runtime-schemas

Plugins that contribute Prisma models (workers, sagas, and auth) need their tables created. With Aspire already running (cd aspire && aspire start), apply migrations and generate the client:

netscript db init --name add-plugin

netscript db generate

netscript db seed

Step 4 — Verify the plugin is registered

List the registered plugins to confirm your new plugin appears:

netscript plugin list

You should see your plugin in the inventory — for example, workers, sagas, triggers, auth, and streams if you added all five. Then run the health check:

netscript plugin doctor

plugin doctor checks installed NetScript plugin health and reports wiring problems (missing registration, port collisions, absent database tables). A clean run means the plugin is registered, wired, and ready to use.

# Detailed info for a single installed plugin
netscript plugin info @netscript/plugin-auth

# Bring the whole stack up and exercise the plugin's service
cd aspire && aspire start
# Aspire dashboard: https://localhost:18888
# auth-api:         http://localhost:<auth-port> (replace with your assigned auth port)

Manage plugins later

Once a plugin is installed you can inspect, update, and remove it without re-scaffolding:

Run netscript plugin --help for the complete, version-accurate command set.

Reference

Where to go next

• Build on the plugin you just added. Next up: Add a service to give the plugin something to call, or Configure authentication if you added the auth plugin.
• Understand the model. Read Plugin architecture for the design behind installable capabilities, ports, and runtime registration.
• Browse capabilities. The capabilities section maps each plugin to the problem it solves, with runnable examples.