diff --git a/src/node-fallbacks/README.md b/src/node-fallbacks/README.md
new file mode 100644
index 0000000000..d2c492a04a
--- /dev/null
+++ b/src/node-fallbacks/README.md
@@ -0,0 +1,11 @@
+# Browser polyfills for `bun build --target=browser`
+
+When using `bun build --target=browser`, if you attempt to import a Node.js module, Bun will load a polyfill for that module in an attempt to let your code still work even though it's not running in Node.js or a server.
+
+For example, if you import `zlib`, the `node-fallbacks/zlib.js` file will be loaded.
+
+## Not used by Bun's runtime
+
+These files are _not_ used by Bun's runtime. They are only used for the `bun build --target=browser` command.
+
+If you're interested in contributing to Bun's Node.js compatibility, please see the [`src/js` directory](https://github.com/oven-sh/bun/tree/main/src/js).
diff --git a/src/node-fallbacks/assert.js b/src/node-fallbacks/assert.js
index 3636f90e31..1e2e54d9da 100644
--- a/src/node-fallbacks/assert.js
+++ b/src/node-fallbacks/assert.js
@@ -1 +1,6 @@
+/**
+ * Browser polyfill for the `"assert"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "assert";
diff --git a/src/node-fallbacks/buffer.js b/src/node-fallbacks/buffer.js
index aa00653982..40febf6828 100644
--- a/src/node-fallbacks/buffer.js
+++ b/src/node-fallbacks/buffer.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"buffer"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "buffer";
 export { Buffer as default } from "buffer";
diff --git a/src/node-fallbacks/console.js b/src/node-fallbacks/console.js
index 34cc54b565..f988876f1a 100644
--- a/src/node-fallbacks/console.js
+++ b/src/node-fallbacks/console.js
@@ -1 +1,6 @@
+/**
+ * Browser polyfill for the `"console"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export default console;
diff --git a/src/node-fallbacks/constants.js b/src/node-fallbacks/constants.js
index 5811eebd4e..2b1bbddf52 100644
--- a/src/node-fallbacks/constants.js
+++ b/src/node-fallbacks/constants.js
@@ -1 +1,7 @@
+/**
+ * Browser polyfill for the `"constants"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
+
 export * from "constants-browserify";
diff --git a/src/node-fallbacks/crypto.js b/src/node-fallbacks/crypto.js
index 65ae2f5b3a..650a945cec 100644
--- a/src/node-fallbacks/crypto.js
+++ b/src/node-fallbacks/crypto.js
@@ -1,3 +1,9 @@
+/**
+ * Browser polyfill for the `"crypto"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
+
 export * from "crypto-browserify";
 import * as cryptoBrowserify from "crypto-browserify";
 
diff --git a/src/node-fallbacks/domain.js b/src/node-fallbacks/domain.js
index af37e70595..58eef6aecc 100644
--- a/src/node-fallbacks/domain.js
+++ b/src/node-fallbacks/domain.js
@@ -1,3 +1,8 @@
+/**
+ * Browser polyfill for the `"domain"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 import domain from "domain-browser";
 export default domain;
 export var { create, createDomain } = domain;
diff --git a/src/node-fallbacks/events.js b/src/node-fallbacks/events.js
index 321f14c204..165fc3d6b4 100644
--- a/src/node-fallbacks/events.js
+++ b/src/node-fallbacks/events.js
@@ -1,3 +1,8 @@
+/**
+ * Browser polyfill for the `"events"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 // Copyright Joyent, Inc. and other Node contributors.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a
diff --git a/src/node-fallbacks/http.js b/src/node-fallbacks/http.js
index ab56f34ebe..46c23595c2 100644
--- a/src/node-fallbacks/http.js
+++ b/src/node-fallbacks/http.js
@@ -1,3 +1,8 @@
+/**
+ * Browser polyfill for the `"http"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 import http from "stream-http";
 export default http;
 export var {
diff --git a/src/node-fallbacks/https.js b/src/node-fallbacks/https.js
index d1de96beb4..228e9dd686 100644
--- a/src/node-fallbacks/https.js
+++ b/src/node-fallbacks/https.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"https"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "https-browserify";
 export * as default from "https-browserify";
diff --git a/src/node-fallbacks/net.js b/src/node-fallbacks/net.js
index d8dc432571..03221037fa 100644
--- a/src/node-fallbacks/net.js
+++ b/src/node-fallbacks/net.js
@@ -1,3 +1,9 @@
+/**
+ * Browser polyfill for the `"net"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
+// -----------------------------------------------------------------------------
 // Copyright Joyent, Inc. and other Node contributors.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a
diff --git a/src/node-fallbacks/os.js b/src/node-fallbacks/os.js
index df0a41fd2b..ec627a9540 100644
--- a/src/node-fallbacks/os.js
+++ b/src/node-fallbacks/os.js
@@ -1,3 +1,9 @@
+/**
+ * Browser polyfill for the `"os"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
+
 import os from "os-browserify/browser";
 export default os;
 export var {
diff --git a/src/node-fallbacks/path.js b/src/node-fallbacks/path.js
index a582c6d0f9..c7977af8eb 100644
--- a/src/node-fallbacks/path.js
+++ b/src/node-fallbacks/path.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"path"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "path-browserify";
 export * as default from "path-browserify";
diff --git a/src/node-fallbacks/process.js b/src/node-fallbacks/process.js
index fec4e652fb..17ebdf5381 100644
--- a/src/node-fallbacks/process.js
+++ b/src/node-fallbacks/process.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"process"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "process/browser";
 export * as default from "process/browser";
diff --git a/src/node-fallbacks/punycode.js b/src/node-fallbacks/punycode.js
index ef8f0464f7..31a3dabf76 100644
--- a/src/node-fallbacks/punycode.js
+++ b/src/node-fallbacks/punycode.js
@@ -1 +1,6 @@
+/**
+ * Browser polyfill for the `"punycode"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "punycode";
diff --git a/src/node-fallbacks/querystring.js b/src/node-fallbacks/querystring.js
index 8c71d38b8a..b58917f2e1 100644
--- a/src/node-fallbacks/querystring.js
+++ b/src/node-fallbacks/querystring.js
@@ -1 +1,6 @@
+/**
+ * Browser polyfill for the `"querystring"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export { decode, default, encode, escape, parse, stringify, unescape, unescapeBuffer } from "querystring-es3";
diff --git a/src/node-fallbacks/stream.js b/src/node-fallbacks/stream.js
index bee941be19..65abe0ba41 100644
--- a/src/node-fallbacks/stream.js
+++ b/src/node-fallbacks/stream.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"stream"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "readable-stream";
 export * as default from "readable-stream";
diff --git a/src/node-fallbacks/string_decoder.js b/src/node-fallbacks/string_decoder.js
index 0def823f82..25ec353409 100644
--- a/src/node-fallbacks/string_decoder.js
+++ b/src/node-fallbacks/string_decoder.js
@@ -1 +1,6 @@
+/**
+ * Browser polyfill for the `"string_decoder"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export { StringDecoder, StringDecoder as default } from "string_decoder";
diff --git a/src/node-fallbacks/sys.js b/src/node-fallbacks/sys.js
index 99f15c638b..228f88ec5a 100644
--- a/src/node-fallbacks/sys.js
+++ b/src/node-fallbacks/sys.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"sys"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "util";
 export * as default from "util";
diff --git a/src/node-fallbacks/timers.js b/src/node-fallbacks/timers.js
index c69274eef9..12cbf9b3bf 100644
--- a/src/node-fallbacks/timers.js
+++ b/src/node-fallbacks/timers.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"timers"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "timers-browserify";
 export * as default from "timers-browserify";
diff --git a/src/node-fallbacks/tty.js b/src/node-fallbacks/tty.js
index 3844312ca4..d0958436cc 100644
--- a/src/node-fallbacks/tty.js
+++ b/src/node-fallbacks/tty.js
@@ -1,3 +1,8 @@
+/**
+ * Browser polyfill for the `"tty"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 let isatty = () => false;
 function WriteStream() {
   throw new Error("tty.WriteStream is not implemented for browsers");
diff --git a/src/node-fallbacks/url.js b/src/node-fallbacks/url.js
index 571d30b934..f33990435e 100644
--- a/src/node-fallbacks/url.js
+++ b/src/node-fallbacks/url.js
@@ -1,3 +1,9 @@
+/**
+ * Browser polyfill for the `"url"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
+// -----------------------------------------------------------------------------
 // Copyright Joyent, Inc. and other Node contributors.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a
diff --git a/src/node-fallbacks/util.js b/src/node-fallbacks/util.js
index 5973068686..c81d2bd7d4 100644
--- a/src/node-fallbacks/util.js
+++ b/src/node-fallbacks/util.js
@@ -1,3 +1,8 @@
+/**
+ * Browser polyfill for the `"util"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "util";
 
 const TextEncoder = globalThis.TextEncoder;
diff --git a/src/node-fallbacks/zlib.js b/src/node-fallbacks/zlib.js
index 093367e295..7904d47136 100644
--- a/src/node-fallbacks/zlib.js
+++ b/src/node-fallbacks/zlib.js
@@ -1,2 +1,7 @@
+/**
+ * Browser polyfill for the `"zlib"` module.
+ *
+ * Imported on usage in `bun build --target=browser`
+ */
 export * from "browserify-zlib";
 export * as default from "browserify-zlib";