@abgov/nx-adsp

Nx plugin for bootstrapping ADSP applications for the Government of Alberta.

The plugin provides generators for Node/Express services, React, Angular, and Vue 3 frontends, .NET services, and fullstack solutions (MERN, MEAN, MEVN, PERN, PEAN, PEVN). When @abgov/nx-oc is also installed, OpenShift deployment YAML is automatically included in the generated output.

Installation

npm i -D @abgov/nx-adsp

Always run nx g @abgov/nx-adsp:init right after installing — see init below.

Prerequisites

Some generators require additional peer dependencies:

Generator	Required peer dependency
`react-app`	`@nx/react`
`angular-app`	`@nx/angular`
`vue-app`	`@nx/vue`
`dotnet-service`	`@nx-dotnet/core`
`react-dotnet`	`@nx/react`, `@nx-dotnet/core`
`express-service`	`@nx/node`
`mern`, `pern`	`@nx/react`, `@nx/node`
`mean`, `pean`	`@nx/angular`, `@nx/node`
`mevn`, `pevn`	`@nx/vue`, `@nx/node`
`react-form`, `react-task-list`	existing React project in the workspace
`vue-detail-view`, `vue-workspace-view`, `vue-admin-crud`, `vue-intake-view`	existing `vue-app` project in the workspace

Generators

init

Sets up nx-adsp’s own workspace-root concerns: installs the ADSP SDK MCP server (@abgov/adsp-sdk-mcp-server) as a dev dependency and registers it in .mcp.json, and shared VS Code settings. Every app/service generator below already runs this as one of its own steps — always run it directly right after installing the plugin, too, so grounded ADSP platform knowledge (tenant/realm/role model, @abgov/adsp-service-sdk reference) is available immediately, not only once you’ve scaffolded your first app. That gap matters for a decision made before any app exists — a design pass, for instance — which a scaffolding-generator side effect can never reach in time.

npx nx g @abgov/nx-adsp:init

No options. Idempotent — merges into existing .mcp.json/.vscode/settings.json without clobbering another server, a customized adsp-sdk entry, a version you’ve pinned yourself, or unrelated settings; safe to re-run. Project-scoped MCP servers only load at session start, so install dependencies and then reconnect (or restart) your MCP client after running this before relying on the new tools — the generator’s own output says so as a reminder.

The server is a dev dependency rather than an on-demand npx -y fetch so that the version your agent executes is the one your lockfile resolved and npm audit can see — along with its transitive dependencies. The .mcp.json entry uses npx --no, which prefers the local install over anything in npm’s _npx cache, and refuses to reach the registry for a version you haven’t installed. Plain npx would fetch and run one silently, because npm assumes --yes whenever stdin isn’t a TTY, as it never is for a stdio MCP server.

One caveat worth knowing: --no treats an already-populated _npx cache entry as satisfying the request, so on a machine that previously ran the npx -y form it will use that cached copy rather than erroring. Run npm install before relying on the pin — with the dependency present, the local copy always wins.

express-service

Creates a Node/Express backend service configured for ADSP.

npx nx g @abgov/nx-adsp:express-service my-service --env dev --tenant my-tenant

Option	Alias	Required	Description
`name`	—	Yes	Name of the service
`env`	`-e`	Yes	ADSP environment: `dev`, `test`, or `prod`
`tenant`	`-t`	No	ADSP tenant name; looks up the Keycloak realm and opens a single browser login
`tenantRealm`	`-tr`	No	Keycloak realm UUID; overrides the realm resolved from `--tenant`
`accessToken`	`-at`	No	Access token for non-interactive retrieval of ADSP configuration
`database`	—	No	Database to scaffold: `none` (default), `postgres` (Drizzle), or `mongo` (Mongoose)
`skipAgent`	—	No	Skip the consultAgent interaction and generate base scaffolding only
`cors`	—	No	Add CORS middleware (`Access-Control-Allow-Origin: *`). Defaults to `true`; set to `false` when the service is paired with a frontend via a same-origin nginx reverse proxy (composite generators do this automatically)
`pairedProject`	—	No	Name of an existing Vue, React, or Angular frontend to pair with this service — wires its nginx proxy, dev-server proxy file, serve target, and `adsp:proxy-service:` tag automatically

Running this generator after the frontend is already scaffolded? Pass --pairedProject <frontend-name> and the generator automatically updates the frontend’s nginx proxy config, vite.proxy.cjs (Vue) or proxy.conf.json (React/Angular), serve target proxyConfig, and adsp:proxy-service: tag — the same wiring the composite generators (mern, mevn, pern, pean, pevn) apply when they run the two generators together. You can also do it the other direction: run the frontend generator with --pairedProject <backend-name> against an already-scaffolded backend (the frontend must already exist for the reverse direction).

When --database postgres is selected the generator scaffolds a Drizzle setup — src/db/schema.ts, a db instance (src/database.ts), a standalone migration runner (src/migrate.ts, bundled to migrate.js for the deploy init container), drizzle.config.ts, an idempotent Podman script for a local Postgres container, and Nx targets (db:generate, db:migrate, db:migrate:deploy, db:studio, dev-db). Drizzle is pure TypeScript with a node-postgres driver — no native engine, so it runs cleanly under OpenShift’s arbitrary UID. When --database mongo is selected it scaffolds a Mongoose connection helper and an equivalent Podman script for a local MongoDB container. See Database setup below.

The generated src/main.ts includes authorize, createValidationHandler, and createErrorHandler from @abgov/adsp-service-sdk, and an example POST /v1/example route that shows the full pattern: role check → input validation (Zod schema) → domain event publish → error forwarding to createErrorHandler. Replace or remove the example route once you have real business logic.

OpenAPI docs are generated from the same Zod schemas already used for request validation (@asteasolutions/zod-to-openapi — see src/openapi.ts) and served at /swagger/docs/v1, with a matching docs link on the root / endpoint. This is what ADSP’s directory service polls to aggregate the service’s API docs into https://api.adsp.alberta.ca/{tenant}, once the service has a directory entry (a one-time setup step, outside this generator).

// Pattern used in the generated example route — adapt for your routes:
app.post(
  '/my-service/v1/resource',
  authorize('my-role'),
  createValidationHandler(MySchema), // validates req.body; 400 on failure
  async (req, res, next) => {
    try {
      const { id } = req.body as z.infer<typeof MySchema>;
      eventService.send(createMyEvent(id));
      res.json({ id });
    } catch (err) {
      next(err); // createErrorHandler maps to 500
    }
  },
);

mern

Composite generator that creates both a React frontend and an Express backend as a fullstack solution. The Express service is pre-configured with MongoDB (Mongoose). Requires @nx/react and @nx/node.

npx nx g @abgov/nx-adsp:mern my-app --env dev --tenant my-tenant

Generates my-app-service (Express + Mongoose) and my-app-app (React), with a dev proxy and nginx production proxy wired between them.

Option	Alias	Required	Description
`name`	—	Yes	Base name; suffixed with `-service` and `-app` for each project
`env`	`-e`	Yes	ADSP environment: `dev`, `test`, or `prod`
`tenant`	`-t`	No	ADSP tenant name
`tenantRealm`	`-tr`	No	Keycloak realm UUID
`accessToken`	`-at`	No	Access token for non-interactive use
`skipAgent`	—	No	Skip the consultAgent interaction and generate base scaffolding only

mean

Composite generator that creates both an Angular frontend and an Express backend as a fullstack solution. The Express service is pre-configured with MongoDB (Mongoose). Requires @nx/angular and @nx/node.

npx nx g @abgov/nx-adsp:mean my-app --env dev --tenant my-tenant

Generates my-app-service (Express + Mongoose) and my-app-app (Angular), with a dev proxy and nginx production proxy wired between them.