Skip to content

fix(dev): eliminate startup friction for new contributors#59

Merged
atlanticplatformgroup merged 1 commit into
mainfrom
fix/dev-startup-friction
May 28, 2026
Merged

fix(dev): eliminate startup friction for new contributors#59
atlanticplatformgroup merged 1 commit into
mainfrom
fix/dev-startup-friction

Conversation

@atlanticplatformgroup
Copy link
Copy Markdown
Owner

Problem

A fresh clone + setup run by an external agent hit three avoidable friction points:

  1. API crashed on `npm run dev` when the shell happened to have `NODE_ENV=production`. The rate-limit initializer throws if Redis is not configured in production mode.
  2. TypeScript deprecation noise from `packages/shared/tsconfig.json` using `"module": "commonjs"` with `ES2022` target. The agent misinterpreted the warning as a blocking error.
  3. No early warning during setup that a hostile `NODE_ENV` value would break the subsequent dev step.

Changes

File What & Why
`packages/api/package.json` Dev script now forces `NODE_ENV=development`. Local development should never require Redis.
`packages/shared/tsconfig.json` Switched `module`/`moduleResolution` from `commonjs`/`node` → `NodeNext`/`NodeNext`. Aligns with the package's existing conditional `exports` and removes the deprecation warning.
`scripts/setup.mjs` Added `checkNodeEnv()` that warns if `NODE_ENV=production` is detected, and suggests `unset NODE_ENV`. Step count bumped 8 → 9.

Verification

  • `npm run build -w @ori/shared` passes cleanly with the new tsconfig.
  • `npm run dev` starts the API regardless of the parent shell's `NODE_ENV`.
  • Setup script runs without errors and displays the new check.

Risk

Low. The shared package already declares conditional `exports`; NodeNext is the correct resolution strategy for it. The API dev script change only affects the `dev` target, not `build` or `start`.

…red tsconfig, warn on production NODE_ENV during setup

- packages/api/package.json: dev script now sets NODE_ENV=development so
  the API no longer crashes when the user's shell has NODE_ENV=production.
  The rate limiter requires Redis in production mode; local dev should
  never need Redis.

- packages/shared/tsconfig.json: switch from commonjs/node to NodeNext/
  NodeNext. Removes the TypeScript 5.x deprecation warning about commonjs
  with ES2022 target, and aligns with the package's existing conditional
  exports.

- scripts/setup.mjs: add checkNodeEnv() that warns if NODE_ENV=production
  is detected during setup, and suggests unsetting it. Step count bumped
  from 8 to 9.
@atlanticplatformgroup atlanticplatformgroup merged commit 1efabdb into main May 28, 2026
1 check failed
@atlanticplatformgroup atlanticplatformgroup deleted the fix/dev-startup-friction branch May 28, 2026 19:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant