1 files changed, 19 insertions, 0 deletions
diff --git a/docs/api/file.md b/docs/api/file.md
new file mode 100644
index 000000000..16e535901
--- /dev/null
+++ b/docs/api/file.md
@@ -0,0 +1,19 @@
+Bun.js has fast paths for common use cases that make Web APIs live up to the performance demands of servers and CLIs.
+
+`Bun.file(path)` returns a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) that represents a lazily-loaded file.
+
+When you pass a file blob to `Bun.write`, Bun automatically uses a faster system call:
+
+```js
+const blob = Bun.file("input.txt");
+await Bun.write("output.txt", blob);
+```
+
+On Linux, this uses the [`copy_file_range`](https://man7.org/linux/man-pages/man2/copy_file_range.2.html) syscall and on macOS, this becomes `clonefile` (or [`fcopyfile`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/copyfile.3.html)).
+
+`Bun.write` also supports [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects. It automatically converts to a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+
+```js
+// Eventually, this will stream the response to disk but today it buffers
+await Bun.write("index.html", await fetch("https://example.com"));
+```