Your backend declares a shop service in its model, and a teammate writes the service’s handler
by copying another one. The model lists one set of messages and the code answers another. A hand
edit to the generated Lambda handler disappears at the next build, because no file in the tree
says which files the build owns.
What you get
You will end up with a booted backend that answers a message the model declares, and a record of which files each regeneration rewrites. This is for you if your services are declared in a model and your team edits the files the model generates.
Short answer
Scaffold the backend with create-system, then use the voxgig-system CLI to append a service, an
entity, a field, a message, and an environment to the model. Run npm run build after each
command. The commands write model lines only, and the build rewrites generated files, so put
each message’s action in its own file under src/srv and never edit a generated file.
You will need
Node 22, and the sample directory with npm ci run in it. The sample holds the project the steps
below produced, so every command on this page runs offline against a scratch copy of it. The
scaffold is a Seneca backend: every service is a set of message
patterns, and @voxgig/system loads the services the model declares.
Expect three workarounds before the scaffold works, each shown below: a shape override to
scaffold, a second one to build, and a model.aontu symlink for the add commands. Two more
defects shape the page. The scaffold’s pinned @voxgig/model cannot move to 12.0.2, and
its tutorial names a model file the scaffold does not write.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/system with create-system | Message services in Seneca, declared in one model that also generates deploy files and docs | Two shape overrides and a symlink before it builds, and a model you keep correct | Your services speak HTTP to each other and the team writes NestJS |
| NestJS CLI schematics | A NestJS app where each controller or resource is written once and then owned | Each run writes files from its options and keeps no model, so the code drifts from any description | Several services must stay in step with one contract |
| NSwag | ASP.NET Core services generated from an OpenAPI document | You run it under .NET, and the compiler, not a boot, reports a missing method | Your services are not .NET |
| Nx generators | A monorepo that wants house conventions in every scaffold | You write and maintain each generator, and a one-shot generator’s output is yours once it runs | The files must follow a model you edit, unless you write a sync generator for it |
| OpenAPI Generator | A NestJS server whose routes come from an OpenAPI document | A beta generator, and a protected controller stops receiving the routes you add | Your services exchange messages, not HTTP requests |
Voxgig maintains @voxgig/system and create-system, the worked path here, and sponsors
Seneca. The other four rows are maintained elsewhere.
The model route keeps services, messages and entities in one place and regenerates from it, at the price of a toolchain that needed three workarounds on the day it ran. A Nest schematic asks for no model, because each run writes its files once and then the files are yours. Nx can keep files in step through sync generators, which you write yourself. OpenAPI Generator and NSwag regenerate from a contract too, but the contract is HTTP and the services are controllers.
Scaffold the backend
The documented npm create @voxgig/system my-app failed in this run, with exit 1 and
TypeError: (0 , shape_1.One) is not a function. The scaffolder pins jostraca 0.41.0, which
calls a shape export that no 12.x release has. Install the scaffolder with shape held at the
last 11.x release instead, through an npm
override.
mkdir tool && cd tool && npm init -y && npm pkg set 'overrides.shape=11.4.1'
npm i @voxgig/create-system@0.10.3 && cd .. && ./tool/node_modules/.bin/create-system my-app
It prints Created my-app/ (36 files). The build inside backend fails the same way through
@voxgig/build, so hold its jostraca’s shape too, then install and build.
cd my-app/backend && npm pkg set 'overrides.jostraca.shape=11.4.1' && npm install && npm run build && npm test
The starter tests report # pass 2. One more step: the CLI looks for model.aontu, and the
scaffold writes model.aon, so every add command fails with model folder not found until you
link the two.
ln -s model.aon model/model.aontu
The CLI’s extension list is ['aontu', 'jsonic'],1 and create-system’s own
tutorial names
model/ent.aontu.
Add a service, an entity, a field, a message, and an environment
Run the five commands in order from my-app/backend, with npm run build after each.
npx voxgig-system add srv shop && npm run build
npx voxgig-system add entity shop/product && npm run build
npx voxgig-system add field shop/product title price:Number && npm run build
npx voxgig-system add msg shop.get.product && npm run build
npx voxgig-system add env aws && npm run build
The sample’s record of each step lists what the command changed and what the build then added, rewrote, or left alone.
node steps.mjs
1. npx voxgig-system add srv shop
the command changed: backend/model/srv.aon
npm run build added: backend/src/handler/lambda/shop.ts
npm run build rewrote: backend/gen/env/aws/srv.yml, backend/model/model.json, docs/reference/messages.md, docs/reference/system-map.md
npm run build left alone: 44 files
2. npx voxgig-system add entity shop/product
the command changed: backend/model/ent.aon
npm run build added: none
npm run build rewrote: backend/gen/api/openapi.json, backend/gen/api/openapi.yaml, backend/model/model.json, docs/reference/entities.md, docs/reference/system-map.md
npm run build left alone: 44 files
3. npx voxgig-system add field shop/product title price:Number
the command changed: backend/model/ent.aon
npm run build added: none
npm run build rewrote: backend/gen/api/openapi.json, backend/gen/api/openapi.yaml, backend/model/model.json, docs/reference/entities.md
npm run build left alone: 45 files
4. npx voxgig-system add msg shop.get.product
the command changed: backend/model/msg.aon
npm run build added: none
npm run build rewrote: backend/model/model.json, docs/reference/messages.md
npm run build left alone: 47 files
5. npx voxgig-system add env aws
the command changed: backend/model/env.aon
npm run build added: backend/gen/env/aws/README.md, backend/gen/env/aws/serverless.yml
npm run build rewrote: backend/model/model.json, docs/reference/system-map.md
npm run build left alone: 47 files
6. write src/srv/shop/shop-srv.ts and src/srv/shop/get_product.ts
written by hand: backend/src/srv/shop/get_product.ts, backend/src/srv/shop/shop-srv.ts
npm run build added: backend/src/srv/shop/README.md
npm run build rewrote: none
npm run build left alone: 53 files
Two things in that record matter more than the rest. No add command wrote service code: the
message step appended one line to msg.aon, and the build rewrote model.json and a generated
reference page.
node steps.mjs msg
4. npx voxgig-system add msg shop.get.product
the command changed: backend/model/msg.aon
+aim: shop: get: product: {}
npm run build added: none
npm run build rewrote: backend/model/model.json, docs/reference/messages.md
npm run build left alone: 47 files
The second is where the build writes. It added src/handler/lambda/shop.ts inside src/, beside
code you own, and a README.md inside src/srv/shop/ once that folder existed. Both are
generated, and the README says so in its first comment.
Write the action the message names
MakeSrv connects the model to the code. For each message the model gives the service, it loads
the action file named after the message’s last pattern pair, so aim:shop,get:product loads
./get_product. That rule is actpath in
system.ts.
// The shop service. MakeSrv reads the model's main.srv.shop and loads one action file per
// message it answers: aim:shop,get:product -> ./get_product.
import { MakeSrv } from '@voxgig/system'
module.exports = MakeSrv('shop', require)
The action loads the entity the model declares, through Seneca’s entity layer.
// The action for aim:shop,get:product, declared in model/msg.aon.
module.exports = function make_get_product() {
return async function get_product(this: any, msg: any) {
const product = await this.entity('shop/product').load$(msg.id)
if (null == product) {
return { ok: false, why: 'not-found' }
}
return { ok: true, product: { id: product.id, title: product.title, price: product.price } }
}
}
These two files are the code you write. Everything under gen/, src/handler/ and
docs/reference/ belongs to the build.
Check it worked
Run npm run build, then boot your own copy with npm run local. It prints
MY-APP-BACKEND STARTED and keeps running, with a REPL on port 50502, the repl port in
model/conf.aon. Open the REPL from a second terminal.
npx seneca-repl telnet://localhost:50502
Type aim:shop,get:product,id:p1 at its prompt. The store starts empty, so the reply is
{ ok: false, why: 'not-found' }. The sample’s script makes the same round trip on a scratch
copy: it boots it the way src/env/local/local.ts does, saves two products, sends the message,
then builds and boots again.
node send.mjs
npm run build, then boot
files the build changed in the committed project: 0
save shop/product {"id$":"p1","title":"Lamp","price":30}
-> {"saved":"p1"}
save shop/product {"id$":"p2","title":"Rug","price":"thirty"}
-> {"error":"shape","message":"Entity: shop/product: Validation failed for property \"price\" with string \"thirty\" because the string is not of type number."}
post {"aim":"shop","get":"product","id":"p1"}
-> {"reply":{"ok":true,"product":{"id":"p1","title":"Lamp","price":30}}}
post {"aim":"shop","get":"product","id":"p2"}
-> {"reply":{"ok":false,"why":"not-found"}}
npm run build again, then boot
files the second build changed: 0
replies identical: true
The reply to aim:shop,get:product carries "title":"Lamp". The price:Number field from step
three is enforced at runtime: the save with a string price is refused. The boot runner turns off
the REPL, because npm run local keeps running until stopped. It printed
MY-APP-BACKEND STARTED { version: '0.0.1' } in the recording.
The test asserts every line of that output, the hand-edit results in the next sections, and each step’s record.
node --test system.test.mjs
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 7783.447136
Add the same operation with OpenAPI Generator and NSwag
A team that generates its services with OpenAPI Generator or NSwag declares the same service as
an OpenAPI document, others/shop-v1.json. Version two adds one operation, listProducts, the
way step four added a message. Each generator then writes the declaration, and your code
implements it in a file the generator never touches.
node others.mjs
OpenAPI Generator 7.27.0, typescript-nestjs-server
files v2 changed: 2
ShopApi v1: getProduct
ShopApi v2: getProduct, listProducts
tsc on shop-impl.ts: v1 exit 0, v2 exit 1
shop-impl.ts(8,14): error TS2515: Non-abstract class 'ShopImpl' does not implement inherited abstract member listProducts from class 'ShopApi'.
HAND EDIT lines in controllers/ShopApi.controller.ts: before 1, after regenerating 0
with the controller in .openapi-generator-ignore: HAND EDIT lines after regenerating 1, listProducts in the controller 0, in ShopApi 1
NSwag version: 14.8.0.0, openapi2cscontroller
IShopController v1: GetProductAsync
IShopController v2: GetProductAsync, ListProductsAsync
OpenAPI Generator’s typescript-nestjs-server, which its page marks beta, writes an abstract
ShopApi class and a controller that calls it. Your implementation extends the class, and TypeScript refuses a subclass that leaves an
abstract member unwritten, so the
added operation is a type error until you write it. The scaffold reports the same gap at boot or at
the call instead.
An edit inside the generated controller is lost on regeneration. Listing the file in
.openapi-generator-ignore keeps the edit,
but the controller then never receives the route for listProducts.
NSwag’s openapi2cscontroller writes one C# file holding an IShopController interface and a
partial ASP.NET Core controller
that forwards each route to it. Its ControllerStyle option takes partial
or abstract, as nswag help openapi2cscontroller prints. A class that implements the v2
interface without ListProductsAsync is the C# compiler’s
CS0535.
The C# was not compiled here, because the sandbox has the .NET runtime and no SDK.
When it goes wrong
A hand edit in a generated file disappears at the next build. The build rewrites gen/,
src/handler/ and the service README from the model, and keeps nothing it did not write. Put
the change in the model, or in the action file, which the build compiles and never rewrites.
node pitfall.mjs
hand edits, then npm run build
lost backend/src/handler/lambda/shop.ts (generated)
lost backend/gen/env/aws/srv.yml (generated)
lost backend/src/srv/shop/README.md (generated)
kept backend/src/srv/shop/get_product.ts (yours)
reply: {"reply":{"ok":true,"product":{"id":"p1","title":"Lamp","price":30,"currency":"EUR"}}}
a message in model/msg.aon with no action file: aim: shop: list: product: {}
npm run build: ok
reload on (npm run local): ready, then aim:shop,list:product -> {"error":"MODULE_NOT_FOUND","message":"Cannot find module './list_product'"}
reload off: FATAL The definition action for the plugin srv_shop has failed: Cannot find module './list_product'
A message declared before its action file builds cleanly and then fails. The system’s
explanation of model wiring
says “A message without an action file fails loudly at boot”. That holds only with reload off,
when the boot logs FATAL and never reaches ready. Under npm run local the system starts and
the call fails with MODULE_NOT_FOUND, because @seneca/reload watches for the missing file instead of refusing it.2 Write the action file in
the same change as the message.
The documented npm create fails with shape_1.One is not a function. A fresh install resolves
shape 12, which lacks that export. Hold it at 11.4.1 through overrides, in the tool folder and
in the backend, as the scaffold steps show.
Moving the backend to @voxgig/model 12.0.2 fails at once with
source not found: @voxgig/model/model/sys.aon, because the scaffold’s model includes a file that
release no longer ships. Keep every release the scaffold pins: the newest @voxgig/build and
@voxgig/system fail the same way as the pinned ones.
When not to do this
Do not use @voxgig/system for a few HTTP endpoints that one team owns. A NestJS schematic or
an Nx generator writes the files once, and then every line is yours to change, with no model to
keep correct. The model earns its upkeep when several services, their messages, their entities
and their deploy files must agree.
Do not adopt the scaffold without pinning it. On the day this page ran, the documented command,
the first build and every add command each needed a workaround, and the newest releases of
@voxgig/build and @voxgig/system failed the same way.
Pick OpenAPI Generator when the contract is HTTP and the team writes NestJS. Its abstract class puts a missing operation in front of the compiler, which a message model cannot do. Pick NSwag for the same reason in ASP.NET Core, where its interface turns an added route into a build error.
Do not edit generated files under any of the three. The scaffold and OpenAPI Generator each discarded a hand edit on regeneration here, and OpenAPI Generator’s ignore file saved an edit only by freezing the file it protected.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/create-system 0.10.3, @voxgig/system
1.15.0, @voxgig/model 11.0.0, @voxgig/build 4.16.0, shape 11.4.1, Seneca 4.0.0-rc5 and
TypeScript 7.0.2, the releases the scaffold installs with shape held by the two overrides. The
same defects held on @voxgig/build 4.16.3 and @voxgig/system 1.15.1, the newest on npm, and
@voxgig/model 12.0.2 failed to build the scaffold’s model, as records/08-*.txt shows. OpenAPI Generator 7.27.0 and NSwag 14.8.0 ran once, in
record-generators.sh, and their output is committed. NestJS CLI schematics and Nx generators
were read from their documentation and not run.
Footnotes
-
The scaffold names its model files
.aon, the CLI looks only for.aontuand.jsonic, and the build script runsvoxgig-model model/model.aon. A symlink is the smallest object that satisfies all three. The extension list sits inlib/add.tsat line 44, in a release whose own reference page names the filessrv.aontuandmsg.aontu. ↩︎ Back to text -
The default that decides which of the two failures you meet is
active: truein@seneca/reload, with the commentNOTE: set to false for production!beside it. Earlier in the same file, a missing action file is watched for creation under the note “calls to the action will still fail”. The scaffold’s local runner leaves the default alone and its Lambda runner turns it off, so development gets the forgiving failure and a deployed function the loud one. ↩︎ Back to text