Eve library

Module System Policy

Guide

Revision 1

On this page

Default stance:

  • Services and shared libraries ship as ESM ("type": "module") with TypeScript module/moduleResolution set to NodeNext.
  • Jest configs stay in .cjs but must treat .js and .ts as ESM (use ts-jest/presets/default-esm where TS is involved).
  • .cjs files 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/export everywhere; if a legacy CommonJS dependency is unavoidable, isolate it in a .cjs wrapper or use createRequire.
  • 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.