ESM Compatibility issue

[DellanX]

Describe the bug

To simplify the process of migrating to TypeConfiguration classes from Declarators, I created a library for housing my models. That all worked fine, and I am set up to finish the migration. Unfortunately, I ran into a speed bump. No matter how I configure my build and test configurations, I run into import CJS issues with this library (as well as entity-store and json-api-entity-provider). Thing is... I am using ESM, not CJS.

I took a deeper look into this library's package.json and dist files, and I think I see the issue.

1. The package.json uses the legacy configuration, pointing to main module and types, instead of exports`
2. The es5 and es2015 do not point to subdirectories in a way compatible with strict ESM environments (such as webpack or vitest)

I'd like to pick your brain on solving this. I could easily add a build tool such as unbuild to compile a .cjs and a .mjs file for compatibility. Since your library doesn't output a .cjs or .mjs file, I think this wouldn't break compatibility. That said, I really don't have experience with UMD vs. ES5 vs. ES2015 vs. ESM.

Let me know what your thoughts are, if you'd like, I can easily create a draft PR.

• in the meantime, I may setup a project on UMD, ES5 and ES2015 to verify compatibility

To Reproduce

Steps to reproduce the behavior:

1. Build this library
2. Check to see if index.js points to subfolders such as functions by syntax ./functions/index

OR

1. Create a library and define some models
2. Add the library to an app, and check that tools such as webpack or vitest run

The log I get, when I brute force ESM:

data-api\node_modules\@dipscope\entity-store\dist\es2015\command-builders' is not supported resolving ES modules imported from data-api\node_modules\@dipscope\entity-store\dist\es2015\index.js

Expected behavior

The ideal solution, would be the ability to consume this library in another library, and import that library in an app.

• ESM would be nice, as that allows for named imports.

Screenshots

If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Windows
• Browser: ESM based node (vitest)

Additional Context

Again, I don't mind adding in build tools and configuring them. I just want to run the idea by you first, and see what you'd like the outcome of the changes to look like. (For example, do you want to make sure that ES5/ES2015/UMD are output, or is just CJS/ESM fine, or all of the above)

[dpimonov]

Hi DellanX,

I don't think the issue is with the library alone, but rather with how the intermediate library is imported and how your setup is configured. The build outputs all formats, including .cjs and .mjs. Even though the extensions may not be explicit in the imports, the files are generated this way to support multiple environments: Node.js, browsers, bundlers, and framework builders such as Angular.

From your error message, it looks like the resolver is picking the correct folder - the es2015 build - and those files clearly use import/export syntax, which indicates ESM. The problem is that in strict ESM mode, Node requires explicit file extensions (e.g. index.js). Since the generated imports rely on TypeScript resolution, there is no explicit index.js and no package.json in that subfolder to let Node resolve it implicitly. When using this library as part of another one, also make sure it is listed as a peerDependency. Most bundlers like Webpack or Vite normally resolve paths correctly, so your final integration step might be the actual source of the issue.

If we are talking about current type manager setup. One way to solve this is to use the nodenext module resolution in TypeScript, which ensures the emitted imports include correct paths according to Node's ESM rules. However, this also requires switching the module setting to nodenext, and I am not certain this will work seamlessly across all supported environments. Such a change would require thorough testing in Node, browsers, bundlers, and framework builds. Most probably using exports field in a package.json and review the build setup across all library chain.

The connections get a bit tricky when combining all three libraries. As a workaround, I am considering adding a minimal package.json with "type": "module" inside the subfolders. That way Node's strict resolver can correctly identify the modules without requiring a stricter setup.

[dpimonov]

By the way, you can try this yourself: add a package.json with { "type": "module" } inside the command-builders folder and see if the error disappears. It would also be very helpful to have a reproduction scenario, since I've never encountered this issue before, even when working with cross-library setups. Normally I use bundlers for the web rather than a pure Node.js environment.

[DellanX]

I'll give your last message a shot, and do some experiments on my side.

Some additional context

• To get the error message above, I deleted the umd and es5 folders from dist, as well as their configurations from package.json. (that's how I forced the resolver to use ES2015, otherwise it kept trying to use CJS)
• I have configured my type to module, and nodenext.

I will experiment with adding a package.json to subdirectories, as well as a few other tricks I'm toying with, to see what I can get to resolve

[DellanX]

Out of curiosity, why not use a build system such as esbuild/webpack/unbuild/tsup to make a single file for es5 and es2015 (potentially giving tree-shaking and minification)? Is there something special about es5/es2015?

[dpimonov]

Tree-shaking works best with unbundled ESM modules. If you publish a single large bundle, downstream bundlers cannot analyze its contents to eliminate unused code, since dead-code elimination relies on per-module ESM graphs.

Different teams also have different browser targets and build pipelines. Pre-minifying or pre-polyfilling the code may lead to unnecessary duplication.

There is nothing special about ES5/ES2015 - they are just language targets, not module systems. I chose that setup originally when configuring the build system.

If you have a clear idea of a more modern approach, please share a sample project or an example library. I would like to first see your setup in practice to better understand what the issue with the current approach is. If it truly is outdated, we can improve it - but this will require updating all five related projects, as I want to avoid having mixed build pipelines. All TypeScript projects currently use the same setup.

The more important to check if UMD modules are still functional when combining multiple libraries. As I already mentioned - they work a bit differently.

[DellanX]

Ah, yes, you are definitely in the right there. (I think I was stuck with tunnel vision after beating my head against a wall, and apologize for my desire to trudge forward)

After probing around, I found:

1. If I reverted to Node16, this would not be an issue at all. I am only running into this because I am trying to run on node20
   • unfortunately, I did not set myself up to be able to revert node versions easily
2. I have 3 other packages in addition to this one that has the same issue. recent versions of node requires the file extension, which is a huge pain.
3. There is an easy to use tool tsc-esm-fix that can run and add the needed extensions. I have a prototype running for this library that fixes my setup.
   • unfortunately, this tool looks for a tsconfig.json file, and doesn't allow specifying a different tsconfig file

I'm going to see if I can pull off (1), I think I may be able to do that if I change some of my dev tools around. That way I get back up on my feet again.

I may also play around with (2) some more and see if I can get a node16 build to live alongside umd/es5/es2015. If I get it working, and working cleanly, I'll create a PR.

• I think the change would just be two files, a tsconfig duplicate of tsconfig.es2015.json, and adding some commands to package.json
• I do want to create some UMD/ES5/ES2015 projects and validate that my changes won't affect them

I remember last time I ran into resolver issues (probably when ES6 came out), I was frustrated to the point I changed back to C++ and PHP
Unfortunately, now I remember why 😆