scripts/build.sh

@@ -11,6 +11,20 @@ DIR="$ROOT/dist"
 rm -rf "$DIR"
 mkdir -p "$DIR"
 
+# We ship 4 builds of this library: ESM and CommonJS, each for Node.js and the Browser.
+# In ./src, code that uses browser APIs lives in `-browser.js` files, while code for node APIs
+# lives in files without suffix.
+# For historical reasons, the Node.js CommonJS build lives in the top level ./dist directory while
+# the other 3 builds live in their respective ./dist/{commonjs,esm}-{node,browser}/ subdirectories.
+#
+# The code below produces this layout:
+#
+#   dist (<-- the commonjs-node build)
+#   ├── commonjs-browser
+#   ├── esm-node
+#   ├── esm-node
+#   └── bin (<-- Node.js CLI)
+
 # Transpile CommonJS versions of files for node
 babel --env-name commonjsNode src --source-root src --out-dir "$DIR" --copy-files --quiet