Developing a node-worker
After generating
Section titled “After generating”Generation already copied .env.example to .env, ran yarn install,
formatted the code, generated the Prisma client against the placeholder model,
and made the first commit.
-
Bring in the API’s models. Copy the API’s
prisma/schema/*.prismaintoprisma/schema/besidebase.prisma, and replace the placeholderUserwith the API’s real one (src/db.tsextensions are typed against aUserwith anemail, so replace it rather than delete it). Better: add the API’s schema directory as a git submodule so both always agree. (In nest-monorepo this step does not exist: the worker imports the API’s client frompackages/db.) -
Point it at the API’s services in
.env:DATABASE_URLandREDIS_*exactly as the API has them. With the API’syarn dc:uprunning, the defaults (localhost:5432,localhost:6379) already match. -
Generate and run:
Terminal window yarn db:generateyarn dev # or yarn dev:watch to restart on changes -
Send it a job from the API (a producer on the
examplequeue), and watchProcessing jobin the log.
Scripts
Section titled “Scripts”| Script | Does |
|---|---|
yarn dev, yarn dev:watch |
Run from source with tsx (the development import condition resolves #app/* to src/) |
yarn build |
Compile to dist/ |
yarn start |
Run dist/ with the instrumentation preload |
yarn db:generate |
prisma generate. With -c studio, Prisma Studio on port 5025; -c push pushes the schema (test/prod only) |
yarn typecheck, yarn lint, yarn format:check |
What CI runs |
yarn secrets [-e prod] |
Pull .env from Infisical (details) |
Imports use Node subpath aliases: #app/* (src/*), #utils/*,
#lib/* and #prisma/* (the generated client), always with a .js
extension, as ESM requires.
Temporal locally
Section titled “Temporal locally”With --with temporal, the worker connects to localhost:7233, the dev server
in the API’s compose.yml. Keep TEMPORAL_TASK_QUEUE equal to the API’s
(main by default). Try it without the API:
temporal workflow execute --type example --task-queue main \ --workflow-id try-1 --input '{"name":"dev"}'The Temporal UI at http://localhost:8233 shows every run, its history and its result.
Building with Claude Code
Section titled “Building with Claude Code”The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:
CLAUDE.mdat the root: the worker’s commands, layout and rules (the API owns the schema, queue names match the producer exactly, throw on failure). Claude Code loads it in every session in the project.- Task skills in
.claude/skills/<name>/SKILL.md: step-by-step recipes that point at the template’s own example code. Ask for the task in plain words (“add an endpoint for invoices”) and the matching skill loads.
| Skill | Ships with | What it does |
|---|---|---|
add-worker | queue | Add a BullMQ queue consumer to this worker for a job the API produces — the queue name, a typed handler, registration and shutdown. |
add-workflow | temporal | Add a Temporal workflow and its activities to this worker — durable, multi-step work the API starts by name (onboarding sequences, provisioning, refunds, anything that waits or must not half-happen). |
A skill that belongs to a feature arrives with it: adding the feature later
with stack add brings its skill and its
CLAUDE.md sections too. Both are yours to edit as the project grows its own
conventions. See Building with Claude Code for
the whole workflow, from a design to a backlog.