docs: clarify CommonJS with optimizeDeps.exclude

[aleclarson]

Description

As a follow-up to #3927, let's clarify that CJS dependencies cannot be added to optimizeDeps.exclude.

Additional context

---

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

[benmccann]

If an ESM dependency has a CommonJS dependency, it also cannot be excluded.

This has been probably the most commonly hit issue for SvelteKit apps. The issue is that all Svelte components need to be excluded (and SvelteKit in fact searches for these packages and automatically adds them to the ssr.noExternal configuration) because the raw .svelte components must be passed to the Svelte compiler. If the package has already been bundled then the .svelte components have already been converted to .js before we try to build the app, which won't work. #3024 refers to this specifically with a lot of people hitting it in the higher traffic #2579.

Is there a way to exclude a package, but have its dependencies optimized? That would help us tremendously. I'm not sure if there's a hard constraint around it being implemented the way it is now or that's just what was done without a specific need for it

[antfu]

Suggested change

	CommonJS dependencies cannot be excluded from optimization. If an ESM dependency has a CommonJS dependency, it also cannot be excluded.
	CommonJS dependencies should not be excluded from optimization. If an ESM dependency has a nested CommonJS dependency, it should not be excluded as well.

[antfu]

I am thinking if we should document to force include the nested dep, eg:

{
  optimizeDeps: {
    exclude: ['esm-dep'],
    include: ['esm-dep-nesed-cjs']
  }
}

[aleclarson]

Does that really work? If so, let's document it

[benmccann]

I know that the below at least works as its something I see people doing all the time:

{
  ssr: {
    noExternal: ['svelte-component']
  }
  optimizeDeps: {
    include: ['svelte-component-dep-nested-cjs']
  }
}

[GrygrFlzr]

Using optimizeDeps.include on a transitive dependency is fragile and is dependent on the flat node_modules used by npm. When pnpm's default nested structure is used, for example, this breaks because the transitive dependency isn't found:

> Failed to resolve force included dependency: clipboard-copy
Error: Failed to resolve force included dependency: clipboard-copy
    at optimizeDeps

Adding the transitive dependency as a direct dependency appears to avoid this issue, but that seems like it'd cause problems in other ways.

[benmccann]

Shouldn't all transitive dependencies be optimized by default? Perhaps the issue here is that Vite's dependency crawling mechanism doesn't work with .svelte files?

[antfu]

I'll merge this for now. Please create a new thread for the future discussion.