Add a note about builtins

1 files changed, 16 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 19f7dcff7..5f7ddbc9c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,6 +53,22 @@ The ESM modules in Bun are located in `src/bun.js/*.exports.js`. Unlike other co
 
 The module loader is in `src/bun.js/module_loader.zig`.
 
+### JavaScript Builtins
+
+JavaScript builtins are located in `src/bun.js/builtins/*.js`.
+
+These files support a JavaScriptCore-only syntax for internal slots. `@` is used to access an internal slot. For example: `new @Array(123)` will create a new `Array` similar to `new Array(123)`, except if a library modifies the `Array` global, it will not affect the internal slot (`@Array`). These names must be allow-listed in `BunBuiltinNames.h` (though JavaScriptCore allowlists some names by default).
+
+They can not use or reference ESM-modules. The files that end with `*Internals.js` are automatically loaded globally. Most usage of internals right now are the stream implementations (which share a lot of code from Safari/WebKit) and ImportMetaObject (which is how `require` is implemented in the runtime)
+
+To regenerate the builtins:
+
+```sh
+make clean-bindings && make generate-builtins && make bindings -j10
+```
+
+It is recommended that you have ccache installed or else you will spend a lot of time waiting for the bindings to compile.
+
 ### Memory management in Bun's JavaScript runtime
 
 TODO: fill this out (for now, use `JSC.Strong` in most cases)