fix(contract) Compile the contract so plain Node can load its runtime constants #13

Merged

araemer merged 2 commits from build-contract-for-node into main

2026-09-26 06:35:32 +00:00

araemer commented

2026-09-26 06:13:22 +00:00

Owner

Problem

recipe-backend crashes at startup on stage since it was onboarded onto the contract (backend PR #13):

ERR_MODULE_NOT_FOUND: Cannot find module '.../recipe-platform/api-contract/src/auth.js'
  imported from .../recipe-platform/api-contract/src/index.ts

The backend imports the contract's as const enum objects (UserRole, RecipeImportStatus, MealPlanPermission, RecipeSortField, …) as values, so its compiled build/*.js keeps import … from "@recipe/contract". Plain Node cannot load src/index.ts. Type-only imports and recipe-app (Vite) were unaffected, which is why the crash didn't show up earlier.

Change

api-contract/package.json
- prepare: tsc (plus a build alias). Every npm install inside api-contract/, both the ONBOARDING step and each sibling's CI install_platform_contract step, now emits dist/ using the existing tsconfig.json. dist/ stays git-ignored.
- Conditional exports map:
  - types → src/index.ts (tsc)
  - module → src/index.ts (Vite client builds)
  - development → src/index.ts (Vite dev server and Vitest; Node never sets this condition)
  - default → dist/index.js (plain Node)
New ADR docs/adr/2026-09-26-contract-node-runtime-build.md. It replaces the "no build step" statement of 2026-09-13-ts-rest-api-contract.md for Node runtimes; that ADR itself is untouched.
CLAUDE.md and ONBOARDING.md document the new rebuild step: after editing the contract, run npm run build in api-contract/ before restarting the backend.

Verification

Backend: tsc passes, 366/366 tests pass, and plain node imports the constants from dist/.
Frontend: tsc -b, 187/187 tests and vite build pass. recipe-app needs no changes.
Both test suites still pass with dist/ deleted, so Vite and Vitest read the source and never see a stale build.

Merge order

Merge this before recipe-backend's ship-built-contract PR. The backend's CI clones recipe-platform at main, so its deploy fix depends on this being there.

🤖 Generated with Claude Code

## Problem `recipe-backend` crashes at startup on `stage` since it was onboarded onto the contract (backend PR #13): ``` ERR_MODULE_NOT_FOUND: Cannot find module '.../recipe-platform/api-contract/src/auth.js' imported from .../recipe-platform/api-contract/src/index.ts ``` The backend imports the contract's `as const` enum objects (`UserRole`, `RecipeImportStatus`, `MealPlanPermission`, `RecipeSortField`, …) as **values**, so its compiled `build/*.js` keeps `import … from "@recipe/contract"`. Plain Node cannot load `src/index.ts`. Type-only imports and `recipe-app` (Vite) were unaffected, which is why the crash didn't show up earlier. ## Change - `api-contract/package.json` - `prepare: tsc` (plus a `build` alias). Every `npm install` inside `api-contract/`, both the ONBOARDING step and each sibling's CI `install_platform_contract` step, now emits `dist/` using the existing `tsconfig.json`. `dist/` stays git-ignored. - Conditional `exports` map: - `types` → `src/index.ts` (`tsc`) - `module` → `src/index.ts` (Vite client builds) - `development` → `src/index.ts` (Vite dev server and Vitest; Node never sets this condition) - `default` → `dist/index.js` (plain Node) - New ADR `docs/adr/2026-09-26-contract-node-runtime-build.md`. It replaces the "no build step" statement of `2026-09-13-ts-rest-api-contract.md` for Node runtimes; that ADR itself is untouched. - `CLAUDE.md` and `ONBOARDING.md` document the new rebuild step: after editing the contract, run `npm run build` in `api-contract/` before restarting the backend. ## Verification - Backend: `tsc` passes, 366/366 tests pass, and plain `node` imports the constants from `dist/`. - Frontend: `tsc -b`, 187/187 tests and `vite build` pass. `recipe-app` needs no changes. - Both test suites still pass with `dist/` deleted, so Vite and Vitest read the source and never see a stale build. ## Merge order Merge this **before** recipe-backend's `ship-built-contract` PR. The backend's CI clones `recipe-platform` at `main`, so its deploy fix depends on this being there. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

araemer added 1 commit

2026-09-26 06:13:22 +00:00

fix(contract) Compile the contract so plain Node can load its runtime constants

/ typecheck-contract (pull_request) Successful in 18s

Details

a14838c4ac

The backend imports the contract's `as const` enum objects as values, so its compiled
output keeps runtime imports of @recipe/contract, which plain Node cannot load from
TypeScript source. The contract now builds to dist/ via a prepare script, and a
conditional exports map sends Node to dist/ while tsc, Vite and Vitest keep reading
src/. See docs/adr/2026-09-26-contract-node-runtime-build.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

araemer added 1 commit

2026-09-26 06:31:43 +00:00

docs(claude) Require marking superseded ADRs, mark the contract ADR

/ typecheck-contract (pull_request) Successful in 19s

Details

1d6cb139bb

The Decision section of 2026-09-13-ts-rest-api-contract.md said "no build
step needed" for consuming the contract, which no longer holds for Node
runtimes since 2026-09-26-contract-node-runtime-build.md. Codify the
missing rule and apply it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

araemer merged commit 6b3339eec5 into main

2026-09-26 06:35:32 +00:00

araemer referenced this pull request from a commit

2026-09-26 06:35:33 +00:00

Merge pull request 'fix(contract) Compile the contract so plain Node can load its runtime constants' (#13) from build-contract-for-node into main

araemer referenced this pull request

2026-10-02 20:17:53 +00:00

Task(api-contract): remove unused zod dependency #7