docs: add troubleshooting for browser compat (#11877)

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>

docs/guide/troubleshooting.md

@@ -121,6 +121,16 @@ You will need to access the file with `http` protocol. The easiest way to achiev
 
 ## Others
 
+### Module externalized for browser compatibility
+
+When you use a Node.js module in the browser, Vite will output the following warning.
+
+> Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.
+
+This is because Vite does not automatically polyfill Node.js modules.
+
+We recommend avoiding Node.js modules for browser code to reduce the bundle size, although you can add polyfills manually. If the module is imported from a third-party library (that's meant to be used in the browser), it's advised to report the issue to the respective library.
+
 ### Syntax Error / Type Error happens
 
 Vite cannot handle and does not support code that only runs on non-strict mode (sloppy mode). This is because Vite uses ESM and it is always [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) inside ESM.

packages/vite/src/node/optimizer/esbuildDepPlugin.ts

@@ -235,7 +235,7 @@ module.exports = Object.create(new Proxy({}, {
       key !== 'constructor' &&
       key !== 'splice'
     ) {
-      console.warn(\`Module "${path}" has been externalized for browser compatibility. Cannot access "${path}.\${key}" in client code.\`)
+      console.warn(\`Module "${path}" has been externalized for browser compatibility. Cannot access "${path}.\${key}" in client code. See http://vitejs.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.\`)
     }
   }
 }))`,

packages/vite/src/node/plugins/resolve.ts

@@ -388,7 +388,7 @@ export function resolvePlugin(resolveOptions: InternalResolveOptions): Plugin {
           return `\
 export default new Proxy({}, {
   get(_, key) {
-    throw new Error(\`Module "${id}" has been externalized for browser compatibility. Cannot access "${id}.\${key}" in client code.\`)
+    throw new Error(\`Module "${id}" has been externalized for browser compatibility. Cannot access "${id}.\${key}" in client code.  See http://vitejs.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.\`)
   }
 })`
         }

playground/optimize-deps/__tests__/optimize-deps.spec.ts

@@ -185,8 +185,12 @@ test.runIf(isServe)('error on builtin modules usage', () => {
   expect(browserErrors.map((error) => error.message)).toEqual(
     expect.arrayContaining([
       // from user source code
-      'Module "buffer" has been externalized for browser compatibility. Cannot access "buffer.Buffer" in client code.',
-      'Module "child_process" has been externalized for browser compatibility. Cannot access "child_process.execSync" in client code.',
+      expect.stringContaining(
+        'Module "buffer" has been externalized for browser compatibility. Cannot access "buffer.Buffer" in client code.',
+      ),
+      expect.stringContaining(
+        'Module "child_process" has been externalized for browser compatibility. Cannot access "child_process.execSync" in client code.',
+      ),
     ]),
   )
 })