docs: Document how to opt into ESM

docs/.vitepress/config.ts

@@ -90,6 +90,7 @@ export default defineConfig({
             { text: 'Assets', link: '/guide/assets.md' },
             { text: 'Content Script UI', link: '/guide/content-script-ui.md' },
             { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
+            { text: 'ES Modules', link: '/guide/esm.md' },
             { text: 'Auto-imports', link: '/guide/auto-imports.md' },
             { text: 'Vite', link: '/guide/vite.md' },
             { text: 'Remote Code', link: '/guide/remote-code.md' },

docs/guide/esm.md

@@ -0,0 +1,38 @@
+# ES Modules
+
+Configure entrypoints to use ESM at runtime.
+
+Currently, ESM entrypoints are opt-in, so you must configure each entrypoint with that in mind.
+
+## HTML Pages <Badge type="warning" text="≥0.0.1" />
+
+In general, you should always make HTML pages import ESM scripts, unless you need to support old browsers.
+
+To make a script ESM, add `type="module"`:
+
+<!-- prettier-ignore -->
+```html
+<script src="./main.ts"></script> <!-- [!code --] -->
+<script src="./main.ts" type="module"></script> <!-- [!code ++] -->
+```
+
+## Background <Badge type="warning" text="≥0.16.0" />
+
+In your background script, set `type: "module"`:
+
+```ts
+export default defineBackground({
+  type: 'module', // !code ++
+  main() {
+    // ...
+  },
+});
+```
+
+:::warning
+Only MV3 support ESM background scripts/service workers. When targetting MV2, the `type` option is ignored and the background is always bundled into a single file as IIFE.
+:::
+
+## Content Scripts
+
+Coming soon. Follow [Content Script ESM Support #357](https://github.com/wxt-dev/wxt/issues/357) for updates.

docs/guide/installation.md

@@ -145,5 +145,6 @@ If you're an experienced web extension developer and think the dev manifest look
 You're ready to build your web extension!
 
 - Learn how to [add entrypoints](./entrypoints) like the popup, options page, or content scripts
+- Configure your entrypoints to [use ESM](./esm) at runtime
 - [Configure WXT](./configuration) by creating a `wxt.config.ts` file
 - Checkout [example projects](https://github.com/wxt-dev/wxt-examples) to see how to perfom common tasks with WXT