Guidance needed: how to configure tooling to use .js file extension in TypeScript imports

[jameshfisher]

Suggestion

It is TypeScript's policy (see #40878) that, if you want tsc --build to produce working JavaScript, the import statements in your TypeScript files must have .js extensions. In @RyanCavanaugh's words: "you should always write the path you want to appear in the emitted JS, and configure the project as necessary to make those paths resolve the way you want during compilation".

There is a long and painful discussion of whether that policy is sensible -- I do not wish to continue that discussion here. What is needed, though, is guidance on how to "configure the project as necessary" to include the .js extension. For example:

• How can we configure VS Code (or any other IDE) to use a .js extension when adding an import statement?
• How can we configure linting tools to warn about extensionless imports, so we don't accidentally commit them?
• How can we automatically fix existing broken codebases that contain extensionless imports?
• How can we configure TypeScript to emit a compile error if encountering an extensionless import?

Despite opening #40878 over 2 years ago, I still don't know the answers to these questions. Judging from other responses, I think a lot of other people are in the same position. @RyanCavanaugh never went into detail on this, and I can't find any guidance in the TypeScript docs. So - people in the know, can you share how you have configured your tools to work around this TypeScript policy?

🔍 Search Terms

js extension tooling

[fatcerberus]

How can we configure TypeScript to emit a compile error if encountering an extensionless import?

This is already enforced for moduleResolution: "node16" and "nodenext". If you're targeting something other than Node, see #52204 and #50153.

How can we configure VS Code ... to use a .js extension when adding an import statement?

"typescript.preferences.importModuleSpecifierEnding": "js"

[jameshfisher]

@fatcerberus Ooh, those are both extremely useful, thank you!

Is there a way to get VS Code to "quick fix" all broken extensionless imports? Or some other one-time script for that? Or should I do some hacky regex?

[jameshfisher]

@fatcerberus this typescript.preferences.importModuleSpecifierEnding preference seems to work for "auto adding" imports, but I've just found a different situation that it doesn't work with: When I move a file, it updates relative imports, but in the process it removes all of my (manually added!) .js extensions. Are there separate preferences for different situations like this? (I couldn't find documentation for typescript.preferences.importModuleSpecifierEnding)

[fatcerberus]

Yikes. Looks like there might be a bug or two with that setting: #46290

[RyanCavanaugh]

We're working on a War-and-Peace-length set of documentation around the module area that will address these questions and many more

[andrewbranch]

It is TypeScript's policy (see #40878) that, if you want tsc --build to produce working JavaScript, the import statements in your TypeScript files must have .js extensions.

Not quite; it’s just that your import statements on the input side need to look like you want them to look on the output side. Extensionless imports work in many places, but not all. Where are you running the JS files emitted by tsc?

[jameshfisher]

Hopefully the new documentation could show how to configure a project to robustly work with fragmented package ecosystem. I haven't been able to find a configuration that lets me just use packages on npm. Latest example with moduleResolution:

• Some packages don't work with node16 or nodenext. For example, Typechecking fails with "moduleResolution": "node16" or "nodenext" syntax-tree/mdast-util-directive#6, and I imagine many others.
• Some packages only work with node16 or nodenext. An example in my project is the conf package: "Cannot find module 'conf'" unless setting "moduleResolution": "node16" or "nodenext" sindresorhus/conf#175

[jmrossy]

We're working on a War-and-Peace-length set of documentation around the module area that will address these questions and many more

Genuinely looking forward to having all the disparate bits of knowledge about modules gathered in one place, thanks! How would I get notified when that's available?

[andrewbranch]

@jmrossy I opened #52593 that you can subscribe to. I’m going to close this one under that umbrella.