Default stance:
- Services and shared libraries ship as ESM (
"type": "module") with TypeScriptmodule/moduleResolutionset toNodeNext. - Jest configs stay in
.cjsbut must treat.jsand.tsas ESM (usets-jest/presets/default-esmwhere TS is involved). .cjsfiles are allowed only for compatibility shims (e.g., adapters around third-party CommonJS code).
Guidelines:
- When adding a new service, use the scaffold (
scripts/scaffold-service.sh) which emits ESM-ready package metadata and Jest config. - Prefer
import/exporteverywhere; if a legacy CommonJS dependency is unavoidable, isolate it in a.cjswrapper or usecreateRequire. - Always include explicit file extensions in relative imports (
./foo.js) to keep NodeNext resolution predictable. - Share code via published/shared packages (token-core, meditation-core, transaction-core, common, lib) instead of cross-importing another service’s source.