raw .ts 배포 + process 참조로 소비자 tsc 실패 (TS2591)

[mundi4]

증상

fuzzly는 exports가 ./src/*.ts를 가리켜 raw TypeScript 소스로 배포된다. 소비자가 fuzzly를 import하면 소비자의 tsc가 fuzzly 소스까지 타입체크하는데, createSearcher.ts의 dev 가드가 node 전역 process를 참조해 @types/node 없는 브라우저 앱에서 타입에러가 난다:

node_modules/fuzzly/src/createSearcher.ts: error TS2591: Cannot find name 'process'.
Do you need to install type definitions for node? ...

해당 코드 (isProd 판정):

return typeof process !== "undefined" && process.env && process.env["NODE_ENV"] === "production";

typeof process !== "undefined" 런타임 가드는 있지만, node 타입이 없으면 TS가 process 심볼 자체를 모른다.

영향

브라우저 앱(예: casely)이 fuzzly를 쓰면 tsc -b가 깨진다. 현재는 소비자 쪽에 앰비언트 declare const process 한 줄을 넣어 우회 중인데, 이는 fuzzly의 패키징 결함을 소비자가 떠안는 것이라 라이브러리에서 고치는 게 맞다.

수정 옵션

1. process 접근을 타입 안전하게 — globalThis를 통해 우회:

   const g = globalThis as { process?: { env?: Record<string, string | undefined> } };
   return g.process?.env?.NODE_ENV === "production";

   node 타입 없이 컴파일되고 런타임 동작 동일.
2. 또는 소스에 최소 앰비언트 선언을 두거나, import.meta.env 기반으로 dev 판정 (Vite 등 번들러 친화적).

참고

• src/createSearcher.ts (isProd IIFE, warnUnknownKeys)
• raw .ts export 정책 자체는 유지해도 되며, 소스가 node 타입 없이 타입체크되기만 하면 됨.