8000 feat: migrated codebase to build both esm and cjs by justinwilaby · Pull Request #193 · heroku/heroku-cli-command · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

feat: migrated codebase to build both esm and cjs #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat: migrated codebase to build both esm and cjs #193

wants to merge 1 commit into from

Conversation

justinwilaby
Copy link
Contributor

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 up 8BCA dated 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@justinwilaby
0