From 3ebe396ce2d04b8bfbbe5f83b2a30b7659f81b03 Mon Sep 17 00:00:00 2001
From: Evan Wallace <evan.exe@gmail.com>
Date: Wed, 28 Feb 2024 23:55:45 +0000
Subject: [PATCH] add a faq entry for not reading the `format` docs

---
 src/content/api.yml |  9 +++++++--
 src/content/faq.yml | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/content/api.yml b/src/content/api.yml
index 4ce95c9..488f282 100644
--- a/src/content/api.yml
+++ b/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
 
diff --git a/src/content/faq.yml b/src/content/faq.yml
index 20ba934..d7b32ea 100644
--- a/src/content/faq.yml
+++ b/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: >