documentation for server.deps.fallbackCJS is confusing

[dctalbot]

Describe the bug

In the main documentation:

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

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

[dctalbot]

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]

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

vitest/packages/vite-node/src/externalize.ts

Lines 29 to 54 in 85fb94a

	export function guessCJSversion(id: string): string | undefined {
	if (id.match(ESM_EXT_RE)) {
	for (const i of [
	id.replace(ESM_EXT_RE, '.mjs'),
	id.replace(ESM_EXT_RE, '.umd.js'),
	id.replace(ESM_EXT_RE, '.cjs.js'),
	id.replace(ESM_EXT_RE, '.js'),
	]) {
	if (existsSync(i)) {
	return i
	}
	}
	}
	if (id.match(ESM_FOLDER_RE)) {
	for (const i of [
	id.replace(ESM_FOLDER_RE, '/umd/$1'),
	id.replace(ESM_FOLDER_RE, '/cjs/$1'),
	id.replace(ESM_FOLDER_RE, '/lib/$1'),
	id.replace(ESM_FOLDER_RE, '/$1'),
	]) {
	if (existsSync(i)) {
	return i
	}
	}
	}
	}

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 thomasbrodusch/vitest-fail-on-console#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"
    }
  }