[api-extractor] Fix self-package import resolution in TypeScript compiler #5301
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
…iler When analyzing .d.ts files that import the package itself, TypeScript's module resolution would redirect to source .ts files instead of analyzing the build artifacts. This occurs because TypeScript tries to avoid analyzing build outputs when outDir/declarationDir are set. Fix by deleting outDir and declarationDir options from the compiler configuration, as API Extractor only uses the compiler for analysis and doesn't emit files. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
finalchild
requested review from
iclanton,
octogonz,
apostolisms,
D4N14L and
dmichon-msft
as code owners
|
@microsoft-github-policy-service agree |
octogonz
reviewed
Aug 8, 2025
| // the .d.ts build artifacts, not the source files. Since API Extractor doesn't emit any | ||
| // files, these options are unnecessary and interfere with correct module resolution. | ||
| delete commandLine.options.outDir; | ||
| delete commandLine.options.declarationDir; |
There was a problem hiding this comment.
Very insightful! I've seen this problem before, but I didn't realize the import analysis was affected by outDir and declarationDir.
octogonz
approved these changes
Aug 8, 2025
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 fixes an issue where API Extractor incorrectly resolves self-package imports to source
.tsfiles instead of the intended.d.tsbuild artifacts.Problem
When a
.d.tsfile imports the package itself by its name, TypeScript's module resolution redirects to source files instead of analyzing the build outputs. This occurs because TypeScript tries to avoid analyzing build outputs whenoutDirordeclarationDircompiler options are set.See the TypeScript compiler logic here: https://github.com/microsoft/TypeScript/blob/391616532d6827254a86dc266121fd5d1958ffb9/src/compiler/moduleNameResolver.ts#L2867
Solution
Remove
outDiranddeclarationDirfrom the compiler options inCompilerState.ts. This prevents TypeScript from redirecting imports and ensures API Extractor analyzes the correct.d.tsfiles. Since API Extractor only uses the compiler for analysis and doesn't emit any files, these options are unnecessary.Test Plan
rushx build.d.tsfilesAlloy issue
I found this issue by trying to build Alloy on a Windows machine. Strangely, this self-import issue causes cyclic dependency warnings only on Windows.
When you run
pnpm exec api-extractor run -v --diagnosticsinpackages/coreof the repository (regardless of the OS), you can see that the compiler is analyzing src directory.After the fix, this changes:
And the Windows issue is also gone.
api.json impact
The members with self-dynamic-import are affected. Others are unaffected.
Before:
After:
As you can see,
!~is changed to!.I don't completely understand what this change is, and which one is better. It seems
!~means local and!means exported?Then!looks fine. The markdown generation was the same (both did not generate the link toChildren).Generated Markdown
Home > @alloy-js/core > MemberName
MemberName() function
Signature:
Returns:
import("@alloy-js/core/jsx-runtime").Children