Add section about napi

1 files changed, 37 insertions, 0 deletions

diff --git a/README.md b/README.md
index 454174c4a..66cf5d930 100644
--- a/README.md
+++ b/README.md
@@ -1895,6 +1895,43 @@ await Bun.write("out.png", png);
 - callback functions
 - async functions
 
+### Node-API (napi)
+
+Bun.js implements 90% of the APIs available in [Node-API](https://nodejs.org/api/n-api.html) (napi).
+
+You can see the status of [this here](https://github.com/Jarred-Sumner/bun/issues/158).
+
+Loading Node-API modules in Bun.js works the same as in Node.js:
+
+```js
+const napi = require("./my-node-module.node");
+```
+
+You can also use `process.dlopen`:
+
+```js
+var mod = { exports: {} };
+process.dlopen("./my-node-module.node", mod);
+```
+
+As part of that work, Bun.js also polyfills the [`detect-libc`](npmjs.com/package/detect-libc) package, which is used by many Node-API modules to detect which `.node` binding to `require`.
+
+This implementation of Node-API is from scratch. It doesn't use any code from Node.js.
+
+Some implementation details:
+
+When requiring a `*.node` module, Bun's JavaScript transpiler transforms the `require` expression into call to `import.meta.require`:
+
+```js
+// this is the input
+require("./my-node-module.node");
+
+// this is the output
+import.meta.require("./my-node-module.node");
+```
+
+Bun doesn't currently support dynamic requires, but `import.meta.require` is an escape hatch for that. It uses a [JavaScriptCore builtin function](https://github.com/Jarred-Sumner/bun/blob/aa87d40f4b7fdfb52575f44d151906ddba6a82d0/src/javascript/jsc/bindings/builtins/js/JSZigGlobalObject.js#L26).
+
 ### `Bun.Transpiler`
 
 `Bun.Transpiler` lets you use Bun's transpiler from JavaScript (available in Bun.js)