1 files changed, 30 insertions, 0 deletions
diff --git a/src/bun.js/builtins/README.md b/src/bun.js/builtins/README.md
new file mode 100644
index 000000000..8ec32e8b5
--- /dev/null
+++ b/src/bun.js/builtins/README.md
@@ -0,0 +1,30 @@
+# JavaScript Builtins
+
+JavaScript files in [./js](./js) use JavaScriptCore's builtins syntax
+
+```js
+@getter
+function foo() {
+    return @getByIdDirectPrivate(this, "superSecret");
+}
+```
+
+It looks kind of like decorators but they're not. They let you directly call engine intrinsics and help with avoiding prototype pollution issues.
+
+V8 has a [similar feature](https://v8.dev/blog/embedded-builtins) (they use `%` instead of `@`)
+
+They usually are accompanied by a C++ file.
+
+The `js` directory is necessary for the bindings generator to work.
+
+To regenerate the builtins, run this from Bun's project root (where the `Makefile` is)
+
+```bash
+make generate-builtins
+```
+
+You'll want to also rebuild all the C++ bindings or you will get strange crashes on start
+
+```bash
+make clean-bindings
+```