Skip to content

Developing a node-worker

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.

  1. Bring in the API’s models. Copy the API’s prisma/schema/*.prisma into prisma/schema/ beside base.prisma, and replace the placeholder User with the API’s real one (src/db.ts extensions are typed against a User with an email, 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 from packages/db.)

  2. Point it at the API’s services in .env: DATABASE_URL and REDIS_* exactly as the API has them. With the API’s yarn dc:up running, the defaults (localhost:5432, localhost:6379) already match.

  3. Generate and run:

    Terminal window
    yarn db:generate
    yarn dev # or yarn dev:watch to restart on changes
  4. Send it a job from the API (a producer on the example queue), and watch Processing job in the log.

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.

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:

Terminal window
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.

The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:

  • CLAUDE.md at 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.
SkillShips withWhat it does
add-workerqueue

Add a BullMQ queue consumer to this worker for a job the API produces — the queue name, a typed handler, registration and shutdown.

add-workflowtemporal

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.