ESM Migration: Plan and known issues documentation #243
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add detailed plan for migrating to moduleResolution node16/nodenext with file extensions in imports. This plan addresses: - #154 - Upgrade moduleResolution from node to node16/nodenext - #110 - Published ESM code has imports without file extensions - #64 - expressions: ERR_MODULE_NOT_FOUND attempting to run example demo script - #146 - Can not import @actions/workflow-parser The migration will: 1. Upgrade TypeScript to 5.7+ 2. Enable rewriteRelativeImportExtensions 3. Add .ts extensions to all relative imports 4. Update JSON imports to use import attributes Implementation will begin after pending PRs are merged to avoid conflicts.
ericsciple
force-pushed
the
users/ericsciple/esm-migration-plan
branch
from
d55352f to
10171d8
Compare
ericsciple
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR documents the ESM migration plan and known issues discovered during implementation attempts.
The plan document (
docs/esm-migration-plan.md) now includes:rewriteRelativeImportExtensionsAlso includes a workaround script (
script/fix-dts-extensions.cjs) for a TypeScript bug.Issues This Will Fix
Closes #154 - Upgrade
moduleResolutionfromnodetonode16ornodenextin tsconfigCloses #110 - Published ESM code has imports without file extensions
Closes #64 - expressions: ERR_MODULE_NOT_FOUND attempting to run example demo script
Closes #146 - Can not import
@actions/workflow-parserKnown Issues Discovered
1. TypeScript Version Conflicts in Monorepo
Root
node_modules/typescriptgets 4.9.5 from ts-node/tsutils. Fix: Add npm overrides.2. ts-jest Incompatible with TypeScript 5.9+
ts-jest 29.4.6 uses
JSDocParsingMode.ParseAllwhich breaks with TS ESM exports. Fix: Use ts-jest 29.0.3 and TypeScript 5.8.3.3. TypeScript
.d.tsExtension BugrewriteRelativeImportExtensionsrewrites.ts→.jsin.jsfiles but NOT in.d.tsfiles. Upstream: microsoft/TypeScript#61037 (unfixed). Workaround: Post-process script included.4. languageserver Tests Hang
Tests pass on main but hang on ESM branch. Status: Needs investigation.
Test Results (December 2025 Attempt)
Status
Related PRs