Skip to content
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

docs: add mitigation section for internal resolution error #218

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add mitigation section for internal resolution error #218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/problems/InternalResolutionError.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,13 @@ This problem can occur with `tsc` alone if the library author compiles with `--m
The problem can also occur when compiling with an unsupported combination of settings, like `--moduleResolution node16 --module esnext`. When either `module` or `moduleResolution` is set to `node16` or `nodenext`, the other setting should always match.

Finally, the problem can occur even when all settings are correct if a package.json is placed into the output directory after a build that changes the module format to/from `"type": "module"`. package.json files affect the detected module format and module resolution, and TypeScript respects the package.json files it sees during compilation in `--moduleResolution node16`. If the set of package.json files that influence the built library are different from the ones TypeScript is aware of during compilation, the results of the compilation can no longer be trusted.

### Mitigation

`node16` module resolution requires explicit file extensions for relative imports.

When a library is authored with relative imports that omit file extensions, the accompanying types generated by `tsc` are likely to be incompatible with `node16` due to extensionless imports in the declaration files. To mitigate this issue, you can:

1. Ensure all relative imports in your source code include file extensions. This behavior is enforced when `node16` or or `nodenext` moduleResolution is used in typescript configuration.
2. Bundle declaration files into a single file (thus avoiding any imports) using bundler plugins like [rollup-plugin-dts](https://www.npmjs.com/package/rollup-plugin-dts).
3. Use independent tools such as [API Extractor](https://api-extractor.com/pages/setup/configure_rollup/) to generate a single declaration file.