How vitest resolves dependency exports

[mkarajohn]

Hi!

so initially I had this issue:

I have a node_modules package that exports

"main": "dist/cjs/index.js",
"module": "dist/esm/index.js",
"types": "dist/types/index.d.ts"

Where the cjs export had been built with tsc --module commonjs and the esm export has been built with tsc --module esnext

The consumer app is set as "type": "module"

Now, vite correctly loads the dist/esm/ export of the package, but vitest loads the dist/cjs/ export.

This causes issues with the tests, that I can resolve if for example I manually edit the package.json of the package to "main": "dist/esm/index.js"

Why does this happen and is it possible to force vitest to consume the esm export?

(original question here: https://stackoverflow.com/questions/77223992/vitest-loads-cjs-export-of-dependency-instead-of-esm)

After a nice discussion on the Vite discord, I learnt about the exports field.

From my testing I can confirm that:

• when a dependency's package.json looks like this

  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/types/index.d.ts",

Vitest will completely ignore the module key, and it will go for main instead.

• when a dependency's package.json looks like this

  "exports": {
    "require": "dist/cjs/index.js",
    "import": "dist/esm/index.js",
    "types": "dist/types/index.d.ts"
  },

or even this

  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/types/index.d.ts",
  "exports": {
    "require": "dist/cjs/index.js",
    "import": "dist/esm/index.js",
    "types": "dist/types/index.d.ts"
  },

Vitest will go for the import key, which is the expected behaviour when the consumer application has "type": "module".

Is this described behaviour documented somewhere that I missed? Should this be documented? (I can open an issue and do that)

Thanks

[sheremet-va]

Vitest will completely ignore the module key, and it will go for main instead.

Vitest has to use Node.js resolution so you don't have multiple instances of the same package, and Node.js doesn't support module field.

Vitest will go for the import key, which is the expected behaviour when the consumer application has "type": "module".

This is not true. import key is chosen when the consumer uses import to import the module.

Is this described behaviour documented somewhere that I missed? Should this be documented? (I can open an issue and do that)

This is just a standard resolution: https://nodejs.org/api/esm.html#resolution-and-loading-algorithm

[mkarajohn]

Ok, cool, thanks for clarifying.

Still, are these mentioned in the documentation somewhere? If not it would be nice to be somewhere.

Like "Q: How does Vitest resolve package exports? A: It uses standard node resolution, blah blah, for more see here: https://nodejs.org/api/esm.html#resolution-and-loading-algorithm"

I am more than happy to open a PR adding this to the docs, if it does not exist (copy can be decided)

[deleugpn]

Okay, after 2 days I land on this which finally gives me some sanity back.

Given that this discussion is the closest thing to explain what's going on, would be wonderful if we could have a reply here or a link on what to do next.

The scenario is:

• I don't own the library I'm installing
• The library works in the browser perfectly fine
• I'm trying to write tests for the feature
• My tests don't work and my feature doesn't behave the same.
• I wrote a console.log() inside the node_modules files and I discovered that:
• • In the browser, the ESM version of the library loads
• • In Vitest, the CJS version of the library loads.

What can I do in code that I own (my tests configuration?, my test file itself?, my component?) to force vitest to load the ESM version of the library the same way that the browser is doing?

[mkarajohn]

Hi!

If you are not the library author, and cannot wait for a PR resolving this, best you can do is

• Install patch-package (https://www.npmjs.com/package/patch-package)
• Go to the package.json file of the offending package
• Add an exports field that includes a require, import, and default fields.
• require exports the CJS code, import exports ESM and default is just a default, usually same as require. Keep in mind that the order matters, so always put default last. If you put default first it will try to load default over anything else.
• Note that paths in the export field must be relative to the file.
• If the package has a more complex export structure for main and module just try to mirror them in the exports field, while keeping in mind the above
• After you have made the required changes, run patch-package <package_name> --exclude 'nothing'
• This will create a patch file of your change in your repo
• If you are using npm add "postinstall": "patch-package" in your scripts. If you are using yarn you still add this, but you will also need to install postinstall-postinstall (see patch-package docs)
• This will allow to apply your patch after someone installs the project's dependencies
• You are set.

If you set up the exports field properly, vitest should now use the ESM export.

As a side, since this happened to at least another person apart from me, I will open a PR adding this in the docs in the next days.

Further reading: https://nodejs.org/api/packages.html#package-entry-points

[mkarajohn]

BTW

to force vitest to load the ESM version of the library the same way that the browser is doing?

Your browser is using the ESM exports because Vite is bundling the ESM export. Vitest resolves differently than Vite (following the Node reolution, instead of what Vite is doing)

[sheremet-va]

Vitest uses the same mechanism to resolve module with two exceptions. Vitest doesn't look at top-level "module" field in package.json, and it prioritizes "node" exports condition. This is needed so you won't have two separate modules imported in cases one of the modules is imported using Native Node resolver (which we can't modify to support "module" field without a big performance hit)

[deleugpn]

This is an unfortunate situation. One of the major benefits of Vite + Vitest is the shared configuration and the single umbrella (owned by the same namespace). It makes things play well with each other. But it appears that even Vite + Vitest has fundamental differences between them that makes them not behave the same. It's already quite challenging to figure out and learn how to play nice with a sea of technology (TS, tsconfig, Vite, Vitest, esbuild, Rollup, Vue, PostCSS, Tailwind, NPM, InertiaJS), having such a relevant conflict within a single toolchain isn't the outcome I would have expected.

[deleugpn]

I managed to make the following workaround for this issue.

On vite.config.js, setup resolve alias as such:

      'vue': 'vue/dist/vue.esm-bundler.js',
      '@highlightjs/vue-plugin': '@highlightjs/vue-plugin/dist/highlightjs-vue.esm.min.js',
      '@tinymce/tinymce-vue': '@tinymce/tinymce-vue/lib/es2015/main/ts/index.js',

These are some example on forcing the module resolution to point to the ESM version instead of the CJS.

[mkarajohn]

Just curious, did you try the patch-package approach?

[deleugpn]

No, I haven't tried that yet, but I kept a local copy to it in case I discover any flaws on my simpler approach

[AllanJard]

Hi - I'm a library author (DataTables.net) and I've just encountered this due to a support question whereby the developers site was working fine in the browser, but failing in a UMD in vitest. DataTables defines both a module and main in package.json, but in the case of the CommonJS file, if there is no global window, then the call signature is slightly different (since DataTables uses it) - you can see that here.

So I'm confused as what I should do as a library author here. It seems to me that if a library defines main and module (which as far as I'm concerned is good practice atm for compatibility) then Vitest is testing different code from what is actually being delivered to the client-side (as built by Vite).

How what Vitest be configured to test the code the client-side will see in such a case?

[sheremet-va]

Docs for the exports field: https://nodejs.org/api/packages.html#package-entry-points

module field is not in the spec, it's something bundlers use, but Node.js doesn't understand it, so we try to avoid relying on module field if we can.

[AllanJard]

Sorry - I might have misunderstood the relationship between vitest and vite - you say that bundlers (including vite) use module at the top level, but vitest doesn't - I'd assumed vitest was a tester for vite bundles. I've just checked with the exports, and it does allow vitest to use the ESM file - thanks for that! Does that mean that packages such as Bootstrap and other popular libraries would also have to adopt the exports object to work with vitest? I'll have a look at what is involved for me to add them to all my packages - I am concerned about what might happen with other bundlers though - it seems like the build systems in Javascript are a tower of cards sometimes :)

[mkarajohn]

t! Does that mean that packages such as Bootstrap and other popular libraries would also have to adopt the exports object to work with vitest?

Yes, if ESM modules are to be used in Vitest they must follow the Node standard on exports.

[sheremet-va]

exports field is the new norm that is meant to work with bundlers and runtime at the same time. All bundlers prefer exports field and fallback to module if there is none. Vitest cannot do that because we run code unbundled inside Node.js which module resolution doesn't support module field.

Vitest actually has support for module field (configured with resole.mainFields) but only for packages imported directly by the source code because it bypasses Node.js module resolution. But for performance reasons, we disable it by default.

I am concerned about what might happen with other bundlers though

All other bundlers support exports field.

[AllanJard]

Amazing - thank you. I'll get this into DataTables and its packages :)

[varugasu]

For lib authors, I managed to solve this problem by adding node in exports:

  "exports": {
    "./*": {
      "types": "./dist/*/index.d.ts",
      "node": "./dist/*/index.cjs",
      "import": "./dist/*/index.mjs",
      "require": "./dist/*/index.cjs"
    }
  },

I was tracking this issue on unjs/unbuild#444