add a faq entry for not reading the format docs

src/content/api.yml

@@ -2628,15 +2628,20 @@ body:
   - ul:
     - >
       In the browser, you can load a module using <code>&lt;script <wbr>src="<wbr>file.js" <wbr>type="<wbr>module"&gt;<wbr>&lt;/script&gt;</code>.
+      Do not forget <code>type="<wbr>module"</code> as this will break your
+      code in subtle and confusing ways (omitting <code>type="<wbr>module"</code>
+      means that all top-level variables will end up in the global scope, which
+      will then collide with top-level variables that have the same name in other
+      JavaScript files).
       <br>&nbsp;
 
     - >
-      In node, you can load a module using <code>node <wbr>--experimental-<wbr>modules <wbr>file.mjs</code>.
+      In node, you can load a module using <code>node <wbr>file.mjs</code>.
       Note that node requires the `.mjs` extension unless you have configured
       <code>"type": <wbr>"module"</code> in your `package.json` file.
       You can use the [out extension](#out-extension) setting in esbuild to
       customize the output extension for the files esbuild generates. You can
-      read more about using ECMAScript modules in node [here](https://nodejs.org/api/esm.html).
+      read more about using ECMAScript modules in node [here](https://nodejs.org/api/esm.html#enabling).
 
   - h3: Global name
 

src/content/faq.yml

@@ -446,6 +446,42 @@ body:
       JavaScript, an untagged template literal is equivalent to a string literal,
       so esbuild is doing the correct thing here.
 
+  - h2#top-level-name-collisions: Avoiding name collisions
+
+  - p: >
+      Top-level variables in an entry point module should never end up in the
+      global scope when running esbuild's output in a browser. If that happens,
+      it means you did not follow [esbuild's documentation about output formats](/api/#format)
+      and are using esbuild incorrectly. **This is not a bug with esbuild.**
+
+  - p: >
+      Specifically, you must do either one of the following when running
+      esbuild's output in a browser:
+
+  - ol:
+    - >
+      <code>--format=<wbr>iife</code> with <code>&lt;script <wbr>src="..."&gt;</code>
+      <p>
+      If you are running your code in the global scope, then you should be using
+      <code>--format=<wbr>iife</code>. This causes esbuild's output to wrap your
+      code so that top-level variables are declared in a nested scope.
+      </p>
+
+    - >
+      <code>--format=<wbr>esm</code> with <code>&lt;script <wbr>src="..." <wbr>type="module"&gt;</code>
+      <p>
+      If you are using <code>--format=<wbr>esm</code>, then you must run your
+      code as a module. This causes the browser to wrap your code so that
+      top-level variables are declared in a nested scope.
+      </p>
+
+  - p: >
+      Using <code>--format=<wbr>esm</code> with <code>&lt;script <wbr>src="..."&gt;</code>
+      will break your code in subtle and confusing ways (omitting
+      <code>type="<wbr>module"</code> means that all top-level variables will end up
+      in the global scope, which will then collide with top-level variables
+      that have the same name in other JavaScript files).
+
   - h2: Top-level `var`
 
   - p: >