Nodejs scaffold
Scaffolds a new Node.js modular-monolith REST API from scratch — empty repo or no package.json. Fastify, code-first OpenAPI via TypeBox, Drizzle + Postgres, JWT auth. Triggers: 'scaffold node api', 'create a fastify backend', 'new node backend'.From its SKILL.md
npx -y skills add tammai/bigin-skills --skill nodejs-scaffoldAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
16.8 KB, as published. Nobody here has run it
nodejs-scaffold
This skill is mechanical: gather config, run the script, relay its output. Do not deliberate — no thinking needed on any step here.
Scaffolds a Node.js REST API from a single template. The mechanical work is done by a deterministic script — scripts/scaffold.mjs (Node stdlib only, cross-platform, zero prompts). This skill's only jobs: decide the CLI flags, run the script, report the result. Do not perform any scaffolding steps yourself.
Stack: Node.js ≥22, Fastify (modular monolith), code-first OpenAPI via TypeBox + @fastify/swagger/@fastify/swagger-ui (route schemas generate src/api/openapi.json), per-module drizzle-orm schemas + postgres (postgres.js) + Postgres with drizzle-kit migrations, JWT (@fastify/jwt, HS256) + argon2id auth, an in-process event bus + graphile-worker job queue (outbox/inbox pattern), Idempotency-Key handling, cursor pagination, a fixed nested error contract, @fastify/cors + @fastify/rate-limit, Fastify's built-in pino logger, ESLint (flat config) with eslint-plugin-boundaries enforcing module boundaries, Vitest.
One template only — no variant menu like nuxt-scaffold's. The generated app ships two example modules proving the full architecture end-to-end: users (create/list/get + auth) and posts (which composes author_name from users through a real cross-module read — the concrete proof the module boundary and batch-get rule work, not an empty folder a lint rule passes on). Everything else about the shape is fixed.
Governance (CLAUDE.md,
.claude/rules/, AI guides,bash-guard.mjs) is not this skill's job — runbigin-harness-setupafterward to overlay it.
Prerequisites: Node.js ≥22 on PATH, pnpm on PATH (corepack enable && corepack prepare pnpm@latest --activate if missing), git. Docker isn't touched by the script (compose/Dockerfile are written but never invoked). Scaffolding is in-place into the target directory (for a brand-new project: mkdir my-api first, or pass --dir).
When not to use
This skill only ever creates a new project. A request about a Node app that already exists belongs elsewhere — even when it names this exact stack. Fastify, Drizzle, TypeBox, the outbox/inbox and the job queue are what this scaffold generates; they are not topics it owns.
- Add a feature, endpoint, migration, or worker to an existing Node API →
task-workflow - Fix a bug or a failing check →
debug-workflow - Explain how a library in the stack works → answer directly, no skill
- Add governance files to an already-scaffolded repo →
bigin-harness-setup
Step 1: Detect state & confirm
Check the target directory:
package.jsonalready exists → complete or partial scaffold from a prior run. Ask: "package.json already exists here — overwrite with --force? (yes / no)". If yes → re-run Step 3 with--force. If no → stop.- No
package.json, directory empty or doesn't exist → ask: "Scaffold a Node.js REST API here (Fastify modular monolith + Drizzle + Postgres)? (yes / no)". If no → stop. - No
package.json, but directory has other files (e.g. a README already committed) → same question, but flag that--forcewill be needed since the script refuses to write into a non-empty directory otherwise.
Step 2: Gather config
One decision matters here — everything else defaults sensibly:
- Project name (required, free text, not
AskUserQuestion— needs regex validation, not a menu) — kebab-case, e.g.orders-api. Drivespackage.jsonname, Docker image name, Postgres user/db, README/OpenAPI title. Ask directly; there's no sensible default. Node has no module-path concept, so--projectis the only required flag.
No AskUserQuestion call needed here — there's no multi-choice decision (this skill has one template, one stack). CORS origins, target directory, and commit behavior all default sensibly (see flag table below); only ask about them if the request implies a specific need (a named frontend origin, scaffolding without git, or maintainer template iteration).
Show a one-line summary and confirm, e.g. Project: orders-api · Dir: . If no → stop.
Step 3: Run the script
node <this-skill-dir>/scripts/scaffold.mjs --project <name> [--dir <dir>] [--cors <origins>] [--force] [--no-commit] [--skip-verify]
| Flag | Default | Purpose |
|---|---|---|
--project | (required) | kebab-case project name |
--dir | . | Target directory |
--cors | http://localhost:3000 | Comma-separated default CORS_ORIGINS |
--force | off | Allow writing into a non-empty directory |
--no-commit | off | Skip git init/add/commit entirely — files are written and verified but nothing is committed |
--skip-verify | off | Write files only — skip pnpm add, codegen, lint, typecheck, build, test, and commit. Maintainer-only, for fast template iteration; never set this from the normal user-facing flow. The result isn't buildable until pnpm install && pnpm db:generate && pnpm openapi:export run manually afterward. |
Stream its output — pnpm add (deps then devDeps) takes the bulk of the time on a fresh run. Every subsequent stage (codegen, openapi:export, lint, type-check, build, test, git commit) is internal — do not duplicate any of it by hand.
Step 4: Report
- Exit 0 → relay the script's "Next steps" output verbatim.
- Exit 2 → bad flags; fix per the error message and re-run.
- Exit 1 → runtime failure; the last
[scaffold] ERROR:line names the failing command (commonly: pnpm not on PATH, Node <22, or a network failure duringpnpm add). Fix the cause and re-run with--force— files from the failed attempt were already written.
Design notes (for maintainers)
- Why isn't any dependency version pinned in
scaffold.mjs, unlike go-scaffold'sSQLC_VERSION/OAPI_CODEGEN_VERSIONconstants? Go's pinning exists specifically to avoid vendoring dev-only tools into the module's owngo.mod. Node has no equivalent problem —pnpm add/pnpm add -Dresolve every dependency here as a normaldependency/devDependencyinto the committedpnpm-lock.yaml. The one exception istypescript@^5(a major-version constraint, not a pin): baretypescriptcurrently floats to a 7.x prerelease with a breakingts.factoryrewrite;^5is the actual compatibility requirement. - Why code-first OpenAPI (TypeBox →
openapi.json) instead of the Go sibling's spec-first (openapi.yaml→ types)? The org-default ADR names code-first as the Fastify default, and it eliminates the ADR's own named anti-pattern (spec and code drifting with no generation step binding them). One TypeBox declaration in each module'sapi/*.schemas.tsis BOTH the runtime validator and the spec source, so they can't diverge.scripts/export-openapi.tsboots the app (no DB — static route-schema introspection, placeholder env) and dumpssrc/api/openapi.json; CI re-exports andgit diff --exit-codes it. Generating frontend TS types from the spec is a consuming frontend scaffold's job, never this backend's —openapi-typescriptwas removed. - Why is Drizzle's codegen direction the reverse of sqlc's? Drizzle is schema-first: each module's
infrastructure/*.schema.tsis hand-written TypeScript, anddrizzle-kit generateproduces migration SQL underdrizzle/from a diff against those schemas (the glob coverssrc/modules/*/infrastructure/*.schema.ts+src/shared/**/*.schema.ts). Repositories call Drizzle's query builder directly — the repository function is the query — with one exception: the cursorlist()path usesqueryClient.unsafewith a spike-verified keyset-WHERE generator (shared/pagination/cursor.ts), because a mixed-direction keyset comparison needs a per-column OR-chain that's cleanest as parameterized raw SQL. Column names there come only from a non-nullable allowlist. - Why
postgres(postgres.js) instead ofpg? It's Drizzle's most-documented default, is promise-first, and doesn't eagerly connect: the process starts cleanly even against an unreachable database, so only/readyz(a real query) surfaces connectivity failures.{ prepare: false }is set because postgres.js's prepared statements don't survive PgBouncer's transaction-pooling mode. - Why migrations are applied manually (
pnpm db:migrate), not at startup. Auto-running migrations at boot races concurrently-starting instances and turns a schema change into an implicit side effect of a restart. Note: one shared migration history spans both modules (the glob) — an accepted limitation of a fixed two-module scaffold, not a per-module-independent-deploy story. - Why Graphile Worker (Postgres-backed), not BullMQ/Redis? The scaffold ships zero infra beyond Postgres. The two jobs (outbox relay, idempotency TTL cleanup) are low-throughput/latency-tolerant; Graphile Worker's job table reuses
DATABASE_URLwith no new compose service. Matches the ADR's "add Redis the moment there's a second instance." The runner runs in-process with the API server because the event bus is in-process — the relay must publish to a bus that already has every module's subscriptions registered. - Why module boundaries need
eslint-plugin-boundaries, and the resolver caveat. Fastify plugin encapsulation enforces nothing about the module boundary — the directory shape is only real becauseboundaries/dependenciesfailspnpm linton an illegal import, and it ships in the same scaffold as the structure (a governed-looking repo that isn't enforced is worse than a flat one). Spike-confirmed trap: enforcement depends oneslint-import-resolver-typescript+settings['import/resolver'].typescript(both wired ineslint.config.mjs); without the resolver,.js-extension imports resolve to unknown elements and violations pass silently.mode: 'file'on the single-fileindex.ts/outbox.tselements is deprecated-but-functional (its replacementpartialMatch: falsewas tested and does not work) — the deprecation warning on lint is expected. - TypeBox + OpenAPI 3.0.3 nullable trap. A raw
Type.Union([T, Type.Null()])emitstype: "null", which is INVALID OpenAPI 3.0.3. Every nullable field uses theNullable()helper inshared/schema/nullable.ts(emitsnullable: true), and enums use{ type, enum }notType.Enum(which emits 3.0-illegalconst). Verified against swagger-parser during the pre-implementation spike. - No Prometheus
/metricsendpoint. A deliberate scope decision (health/readiness/logging/CORS/rate-limit are covered) — go-scaffold's/metricsviapromhttpremains the one known go/nodejs parity gap; a small future addition would beprom-client+ a/metricsroute. - Each module plugin gets its own
/v1/<module>prefix (usersRoutes→/v1/users,authRoutes→/v1/auth,postsRoutes→/v1/posts), matching the ADR's wiring example. Self-erase (DELETE /v1/users/:id) lives inusers.routes.ts, notauth.routes.ts— it's a users-resource operation, not a credential operation, even thougheraseUseris exported from the sameapplication/erase-user.tseither way. - Optimistic concurrency (ADR §9.4) is demonstrated on
posts, notusers.PATCH /v1/posts/:idrequires the caller's currentversionin the body; a mismatch is a 409, never a silent overwrite — enforced twice (a pre-check inupdate-post.use-case.tsfor a fast, readable error, and the real guard inposts.repository.ts#updateWithVersion's conditionalWHERE version = $expected, which is what actually closes the TOCTOU race between the two). The route also setsidempotent: true, the exact pairing ADR §9.3 calls out: a network retry of a successful update replays the stored response instead of hitting a bogus 409 against the now-bumped version. - Dead-letter handling is a real DLQ table with backoff, not just a status flag. After a publish attempt fails,
outbox-relay.tssetsnext_attempt_at(1 min, then 5 min) instead of retrying every cron tick; afterMAX_ATTEMPTS(3) it copies the row intoshared.dead_letter_events(shared/job-queue/dead-letter.schema.ts) and flags the source row'sdead_lettered_atso the relay stops re-selecting it — the DLQ table is what stays queryable for manual inspection. - Testing is split unit vs. integration, and only unit runs during scaffolding.
*.test.ts(domain/application, mocked repositories — no DB) is the defaultpnpm test, including duringscaffold.mjs's own verification pass.*.integration.test.ts(infrastructure repositories + one fullapp.injectHTTP round trip, real Postgres) ispnpm test:integration, wired to a separatevitest.integration.config.tswhoseglobalSetup(tests/global-setup.ts) starts a Postgres testcontainer, applies the committeddrizzle/*.sql, and tears it down. Deliberately not run byscaffold.mjsitself — requiring Docker during scaffolding would break the "leaves a green repo, no manual fixup" guarantee on any machine without a running daemon. CI runs both (ubuntu-latestships Docker, sotest:integrationneeds noservices:block). pnpm dev:setupandscripts/seed.ts. One entrypoint (docker compose up -d db && pnpm db:migrate && pnpm seed) gets a new engineer a working dataset (one admin user + one post) instead of a wiki page of manual steps. The seed is idempotent by pre-checking for the seed email rather thanON CONFLICT—users' unique index is partial (WHERE deleted_at IS NULL), and matching that predicate fromonConflictDoNothingwould just duplicate the same condition in two places.
Manual validation (maintainers)
After changing scaffold.mjs or templates, verify in an empty temp dir:
mkdir scaffold-test && cd scaffold-test
node <skill-dir>/scripts/scaffold.mjs --project scaffold-test --dir .
Expect: exit 0, pnpm lint (incl. boundary lint) / pnpm type-check / pnpm build / pnpm test --run all pass inline, src/api/openapi.json written, a git commit created. Watch the first pnpm add/pnpm add -D for ERR_PNPM_IGNORED_BUILDS — if a package other than argon2/esbuild needs a native build, add it to package.json's pnpm.onlyBuiltDependencies and the relevant pnpmAdd approvable list in scaffold.mjs.
Confirm boundary enforcement actually fires: temporarily add a cross-module import that reaches past a module's index.ts (e.g. import { usersRepository } from '../../users/infrastructure/users.repository.js' inside posts/application/list-posts.use-case.ts) and confirm pnpm lint fails with a boundaries/dependencies error, then revert.
Then run the integration suite — it IS the golden path (signup → login → create post → list shows author_name → stale-version PATCH gets 409 → correct-version PATCH succeeds → erase → outbox relay ticked manually → post anonymizes), against a real Postgres via testcontainers, no manual docker compose/curl needed:
pnpm test:integration # needs Docker; starts + tears down its own Postgres container
For a from-scratch manual poke instead (e.g. checking /docs renders, or a behavior app.inject can't exercise like real network binding):
cp .env.example .env # set a JWT_SECRET
pnpm dev:setup # docker compose up -d db + migrate + seed
node dist/server.js & # or pnpm dev
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/healthz # 200
Re-run the same scaffold command again without --force → must fail fast ("exists and is not empty"), exit 2, no files touched.
For a fast file-tree-only pass while iterating on templates, add --skip-verify — expect exit 0 in a couple seconds, no install/codegen/build/commit; inspect the written files directly.
References
scripts/scaffold.mjs— the scaffold implementation (single file, Node stdlib only). Discovers template files by recursively walkingscripts/templates/files/and writes them all in one pass (no STATIC/GLUE split — code-first OpenAPI removed the ordering dependency), then runspnpm add→drizzle-kit generate→openapi:export→ lint/type-check/build/test → commit. Never runspnpm test:integrationitself (see the testing design note above).scripts/templates/files/— source of truth for every file written into the project.src/api/openapi.jsonanddrizzle/*.sqlare NOT here — they're generated during the run and committed.tests/global-setup.tsandvitest.integration.config.tsare the testcontainers wiring forpnpm test:integration;scripts/seed.tsbackspnpm dev:setup.