docs: Add missing ssr.noExternal docs to vite-node loader

docs/.vitepress/config.ts

@@ -142,7 +142,7 @@ export default defineConfig({
           menuItem('Custom Events', 'custom-events'),
           menuItem('Reusable Modules', 'reusable-modules'),
           menuItem('Remote Code', 'remote-code'),
-          menuItem('Entrypoint Side Effects', 'entrypoint-side-effects'),
+          menuItem('Entrypoint Loaders', 'entrypoint-loaders'),
           menuItem('How WXT Works', 'how-wxt-works'),
         ]),
         menuGroup('Upgrade Guide', '/guide/upgrade-guide/', [

docs/guide/go-further/entrypoint-loaders.md

@@ -1,6 +1,6 @@
 # Entrypoint Loaders
 
-Because entrypoint options, like content script matches, are listed in the entrypoint's JS file, WXT has to import them during the build process to use those options when generating the manifest.
+Because entrypoint options, like content script `matches`, are listed in the entrypoint's JS file, WXT has to import them during the build process to use those options when generating the manifest.
 
 There are two options for loading your entrypoints:
 
@@ -11,7 +11,50 @@ There are two options for loading your entrypoints:
 
 Since 0.19.0, WXT uses `vite-node`, the same tool that powers Vitest and Nuxt, to import your entrypoint files.
 
-There isn't really anything to add here... By default, it should "just work".
+If you use any runtime packages that depend on `webextension-polyfill`, you need to add them to [Vite's `ssr.noExternal` option](https://vitejs.dev/config/ssr-options#ssr-noexternal):
+
+```ts
+export default defineConfig({
+  vite: () => ({
+    ssr: {
+      noExternal: ['@webext-core/messaging', '@webext-core/proxy-service'],
+    },
+  }),
+});
+```
+
+:::details Why?
+This tells Vite it needs process these module's, letting WXT properly disable the polyfill in the NodeJS environment so it doesn't cause any build errors like this:
+
+```
+ERROR This script should only be loaded in a browser extension
+```
+
+:::
+
+To get a list of installed packages that use on `webextension-polyfill`, run your package manager's `list` command. Here's an example with PNPM:
+
+```sh
+$ pnpm why webextension-polyfill
+
+dependencies:
+@webext-core/messaging 1.4.0
+└── webextension-polyfill 0.10.0
+@webext-core/proxy-service 1.2.0
+├─┬ @webext-core/messaging 1.4.0 peer
+│ └── webextension-polyfill 0.10.0
+└── webextension-polyfill 0.12.0 peer
+
+devDependencies:
+@wxt-dev/module-vue 1.0.0
+└─┬ wxt 0.19.0-alpha1 peer
+  └── webextension-polyfill 0.12.0
+webextension-polyfill 0.12.0
+wxt 0.19.0-alpha1
+└── webextension-polyfill 0.12.0
+```
+
+Ignoring WXT itself (it's added automatically for you), there are three packages that depend on the polyfill: `@wxt-dev/module-vue`, `@webext-core/messaging`, and `@webext-core/proxy-service`. Since the vue module is a build dependency, with no runtime code, you don't have to add it. That means for this case, you need to add `@webext-core/messaging`, and `@webext-core/proxy-service`, as shown in the original code snippet.
 
 ## jiti
 

docs/guide/upgrade-guide/wxt.md

@@ -14,37 +14,57 @@ If there was a major version change, follow the steps below to fix breaking chan
 
 ### `vite-node` Entrypoint Loader
 
-The default entrypoint loader has changed to `vite-node`. This change enables:
+The default entrypoint loader has changed to `vite-node`. If you use any NPM packages that depend on the `webextension-polyfill`, you need to add them to Vite's `ssr.noExternal` option:
 
-- Importing variables and using them in the entrypoint options.
+```ts
+export default defineConfig({
+  vite: () => ({
+    // [!code ++]
+    ssr: {
+      // [!code ++]
+      noExternal: ['@webext-core/messaging', '@webext-core/proxy-service'], // [!code ++]
+    }, // [!code ++]
+  }), // [!code ++]
+});
+```
 
-  ```ts
-  // entrypoints/content.ts
-  import { GOOGLE_MATCHES } from '~/utils/constants'
+> [Read the full docs](/guide/go-further/entrypoint-loaders#vite-node) for more information.
 
-  export default defineContentScript({
-    matches: [GOOGLE_MATCHES],
-    main: () => ...,
-  })
-  ```
+:::details This change enables:
 
-- Use Vite-specific APIs like `import.meta.glob` to define entrypoint options.
+Importing variables and using them in the entrypoint options:
 
-  ```ts
-  // entrypoints/content.ts
-  const providers: Record<string, any> = import.meta.glob('../providers/*', {
-    eager: true,
-  });
+```ts
+// entrypoints/content.ts
+import { GOOGLE_MATCHES } from '~/utils/constants'
 
-  export default defineContentScript({
-    matches: Object.values(providers).flatMap(
-      (provider) => provider.default.paths,
-    ),
-    async main() {
-      console.log('Hello content.');
-    },
-  });
-  ```
+export default defineContentScript({
+  matches: [GOOGLE_MATCHES],
+  main: () => ...,
+})
+```
+
+Using Vite-specific APIs like `import.meta.glob` to define entrypoint options:
+
+```ts
+// entrypoints/content.ts
+const providers: Record<string, any> = import.meta.glob('../providers/*', {
+  eager: true,
+});
+
+export default defineContentScript({
+  matches: Object.values(providers).flatMap(
+    (provider) => provider.default.paths,
+  ),
+  async main() {
+    console.log('Hello content.');
+  },
+});
+```
+
+Basically, you can now import and do things outside the `main` function of the entrypoint - you could not do that before. Still though, be careful. It is recommended to avoid running code outside the `main` function to keep your builds fast.
+
+:::
 
 To continue using the old approach, add the following to your `wxt.config.ts` file: