documentation for `server.deps.fallbackCJS` is confusing

dctalbot commented 1 month ago

Describe the bug

When a dependency is a valid ESM package, try to guess the cjs version based on the path. This might be helpful, if a dependency has the wrong ESM file.

I'm not sure what this means. If a dependency is valid ESM, why would it look for a CJS version? What does it mean to "have the wrong ESM file"?

The IDE documentation:

Try to guess the CJS version of a package when it's invalid ESM

This seems to contradict the previous statement. Does this setting take affect when an ESM dependency is valid or invalid?

Reproduction

View the documentation

System Info

N/A

Used Package Manager

npm

Validations

[X] Follow our Code of Conduct
[X] Read the Contributing Guidelines.
[X] Read the docs.
[X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
[X] Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
[X] The provided reproduction is a minimal reproducible example of the bug.

dctalbot commented 1 month ago

Asking because I'm having an issue with vitest-fail-on-console, and it's unclear to me what the expected behavior of vitest is.

hi-ogawa commented 1 month ago

When a dependency is a valid ESM package, try to guess the cjs version based on the path. This might be helpful, if a dependency has the wrong ESM file.

I think the only way to correctly describe what this does is to understand this code https://github.com/vitest-dev/vitest/blob/85fb94a3081558b01f47bd763ccdaeb5df1b98cb/packages/vite-node/src/externalize.ts#L29-L54

And probably it's a typo of "invalid ESM package", but note that this fallback guessing is only a heuristics, so we cannot really say what is "invalid ESM package" or not.

I think nowadays fallbackCJS is probably not necessary for many cases. If you need to workaround wrong esm packaging issues, then you might be able to target it better with server.deps.inline https://vitest.dev/config/#server-deps-inline

Regarding your main issue on https://github.com/thomasbrodusch/vitest-fail-on-console/issues/59, I think their packaging is not ideal and goes wrong with fallbackCJS: true unfortunately. You can take a look at this https://publint.dev/vitest-fail-on-console@0.7.0 and they are shipping both ./dist/vitest-fail-on-console.es.js and ./dist/vitest-fail-on-console.umd.js with "type": "module". Since Vitest only runs esm in the test environment (doesn't use require), I think they can only ship something like:

  "exports": {
    ".": {
      "type": "./dist/index.d.ts",
      "default": "./dist/vitest-fail-on-console.es.js"
    }
  }

vitest-dev / vitest