feat: migrated codebase to build both esm and cjs

[justinwilaby]

Overview

This PR migrates the codebase to native ECMAScript Modules (ESM) while also supporting CommonJS (CJS) builds. The update modernizes the project, improves compatibility with the latest Node.js and tooling, and ensures continued support for consumers requiring CJS.

Key Features

• Full migration of all source files to ESM syntax (import/export, file extensions, etc.)
• Dual build output: generates both ESM (lib/esm) and CJS (lib/cjs) distributions
• Updated package.json with proper exports, main, and module fields for dual support
• Automated post-build script to set correct "type" in output directories
• Removal of legacy dependency injection (deps.ts) in favor of direct imports
• Updated all import paths and test files for ESM compatibility
• Upgraded dependencies for ESM/CJS compatibility and latest features
• Improved build, lint, and test scripts for the new module system

Technical Details

• Implementation:
  • All source and test files now use ESM import/export syntax, including explicit .js extensions for local imports.
  • The build process uses TypeScript to output both ESM and CJS modules to separate directories.
  • A new script (scripts/write-type-package-jsons.mjs) writes a package.json with the correct "type" field to each output directory.
  • The package.json now uses the exports field to provide both ESM and CJS entry points, and sets main, module, and types accordingly.
  • The legacy deps.ts indirection is removed; all dependencies are now imported directly.
  • All Node.js built-in modules are imported with the node: prefix for ESM compatibility.
  • Test and helper files are updated for ESM and Node.js 20+ compatibility.
• Error Handling:
  • No changes to runtime error handling logic; only module system and import paths are affected.
• Configuration:
  • tsconfig.json updated for ESM output, modern target, and correct module resolution.
  • Linting and formatting scripts updated for ESM and Prettier 3.

Testing Instructions

Prerequisites:

• Node.js 20 or later
• Clean install: rm -rf node_modules lib && npm install

Build:

• Run npm run build
  • This will lint, format, and build both ESM and CJS outputs.

Test:

• Note that npm test fails for now. The test config will be updated before merging.
  • All tests should pass using the ESM build and loader once this is done.

Manual Verification:

• run npm run build && npm pack then copy the absolute path of the tarball. Use yarn add or npm i -S and paste the path of the tarball in your test project (Heroku CLI in this case)
• Import the package as both ESM and CJS in a test project:
  • ESM: import { Command } from 'heroku-cli-command'
  • CJS: const { Command } = require('heroku-cli-command')
• Verify that both entry points work as expected.

Expected Results:

• Both ESM and CJS consumers can import and use the package.
• CLI and library usage remain unchanged for end users.

Impact

• Modernizes the codebase for long-term maintainability and compatibility with current/future Node.js versions.
• Enables consumers to use either ESM or CJS, broadening adoption.
• Removes legacy indirection, simplifying the codebase and reducing technical debt.
• Upgrades dependencies for improved security and performance.

Future Considerations

• Deprecate CJS build in a future major release once ESM adoption is universal.
• Monitor for any downstream consumer issues with dual module support.
• Consider publishing ESM-only in the future to further simplify the codebase.
• Update documentation and examples to reflect ESM-first usage.