What’s confusing about modules?

[andrewbranch]

After #51669 is merged, I plan to write documentation for it, and try to update/rewrite a bunch of our existing module-related documentation. While there are a lot of good examples in this issue tracker of specific questions and misconceptions about modules and TypeScript’s module-related options, I thought I’d ask explicitly what questions you have and what aspects of the module landscape or our configuration specifically are the most confusing.

[GabenGar]

Is there a difference between import moduleName from "module-path"; and import { default as moduleName } from "module-path";?

[andrewbranch]

(I don’t plan to answer all or even most questions here, but if the answer is quick and contains any context that may not make it into the docs, I might.)

@GabenGar no, except there accidentally was a difference in type resolution for a while, but it’s fixed now: #49567 fixed by #49814

[treybrisbane]

Any chance you could include a dedicated section or two on why it's not practical to have the compiler transform imports ending in .ts to ones ending in .js? 🙂

I've seen a few of the TypeScript team posting some pretty solid rationale in various GitHub comments over the years, but I can never remember all the reasons, and finding those comments again is quite difficult. It would be amazing to get one clear, objective, well-written explanation/rationale that could be easily linked to by anyone whenever this comes up.

[IanVS]

One thing that tripped me up was how .mts and .cts files interact with package.json exports fields. Especially in the case of dynamic import() (which always uses the import condition, even in .cts files).

[Andarist]

What are the exact requirements for publishable packages? And how do they relate to: package.json#type, package.json#exports, moduleResolution values? When do extensions in .d.ts matter? And what they should be?

[khmseu]

An import path cannot end with a '.mts' extension. Consider importing './XXX.mjs' instead.

Why does this error message even exist? It seems insane to direct tsc to import a .mjs when we have a .mts with types and everything. What am I missing here? Is there a way to direct tsc to the real type info? That suggestion certainly doesn't sound like something I want to do.

[unional]

I'm working on a demo about many issues with the current module, moduleResolution, allowSyntheticDefaultImports, and esModuleInterop combinations.

It's still a work in progress. I can probably finish it by this weekend or next week.

Feel free to check it out or cooperate about this topic.

https://github.com/cyberuni/typescript-module-resolutions-demo

[bobaaaaa]

My team is building a non-fancy web-app (not a library/framework) in a monorepo setup. Are there any different configs needed for app vs. library authors?

I would love to see some kind of cli check -> "Is my setup ok?" like brew doctor or https://github.com/bluwy/publint

[unional]

Cross linking the great post made by Ryan: #49083 (comment)

There are still many things worth to discuss and figure out, for example:

• How to actually consume packages in today's CJS/ESM world
• How to support both as a library? Maintaining multiple versions? Duplicate code?
• How to make the life of TypeScript library authors easier today. What can be done by TypeScript, community tools, library authors?
• What's the TypeScript and JavaScript community direction

But in general, that is a good read and should check it out.

[GabenGar]

In regards to second option, create a major version increase and ditch CJS with it. Supporting both will not make it easier neither for you nor consumers.

[unional]

In regards to second option, create a major version increase and ditch CJS with it. Supporting both will not make it easier neither for you nor consumers.

In theory, yes.

But in practice, it's not that straight forward. It mainly come down to environment and tooling.

For example, I have a project that wants to be consumed as ESM, and at the same time, used as part of the global setup when running jest.
Even today, with jest 29.4.2, doing NODE_OPTIONS=--experimental-vm-modules, using @repobuddy/jest etc. The global setup script still looks for the CJS variant in the exports field.

The situation is even harder within corporations, where you want to write some tools and use them in the company.
There are products written many years ago and they simply can't migrate to ESM only toolchain, and probably never will.

Then what are you going to do? Supporting CJS only is not an option as you DO want to move your toolchain forward. You don't want to be part of the problem. So dual release or maintaining multiple versions is the only option.

Then, that comes to cost management. As managing multiple versions requires additional time, effort, and ultimately, moola.

[GabenGar]

For example, I have a project that wants to be consumed as ESM, and at the same time, used as part of the global setup when running jest.
Even today, with jest 29.4.2, doing NODE_OPTIONS=--experimental-vm-modules, using @repobuddy/jest etc. The global setup script still looks for the CJS variant in the exports field.

You don't it find comical that a testing framework stands in a way of major version upgrade, even though the whole point of adhering to the TDD dogma is to reduce the pain of major refactors?
It's time to switch to a testing framework which understands ESM (aka modern nodejs code), which means no magical bloated packages which transpile on the fly into who knows what and output green checkboxes. And yes, it does mean you can't run your unit tests without building them and the underlying code first.

The situation is even harder within corporations, where you want to write some tools and use them in the company.

This is kinda the company's problem. For that just transpile your code to cjs and don't worry. The only real enterprise way.

There are products written many years ago and they simply can't migrate to ESM only toolchain, and probably never will.

Then it should lock down dependencies and run on outdated stack forever,

Then, that comes to cost management. As managing multiple versions requires additional time, effort, and ultimately, moola.

It's actually even worse than management and development. Dual packages are the subject to dual-package hazard and that can contribute subtle bugs, which are pretty hard to debug and resolve.