1 files changed, 121 insertions, 0 deletions
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
new file mode 100644
index 000000000..3d7943423
--- /dev/null
+++ b/docs/benchmarks.md
@@ -0,0 +1,121 @@
+Bun.js focuses on performance, developer experience, and compatibility with the JavaScript ecosystem.
+
+## HTTP Requests
+
+```ts
+// http.ts
+export default {
+  port: 3000,
+  fetch(request: Request) {
+    return new Response("Hello World");
+  },
+};
+
+// bun ./http.ts
+```
+
+| Requests per second                                                    | OS    | CPU                            | Bun version |
+| ---------------------------------------------------------------------- | ----- | ------------------------------ | ----------- |
+| [260,000](https://twitter.com/jarredsumner/status/1512040623200616449) | macOS | Apple Silicon M1 Max           | 0.0.76      |
+| [160,000](https://twitter.com/jarredsumner/status/1511988933587976192) | Linux | AMD Ryzen 5 3600 6-Core 2.2ghz | 0.0.76      |
+
+{% details summary="See benchmark details" %}
+Measured with [`http_load_test`](https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c) by running:
+
+```bash
+$ ./http_load_test  20 127.0.0.1 3000
+```
+
+{% /details %}
+
+## File System
+
+`cat` clone that runs [2x faster than GNU cat](https://twitter.com/jarredsumner/status/1511707890708586496) for large files on Linux
+
+```js
+// cat.js
+import { resolve } from "path";
+import { write, stdout, file, argv } from "bun";
+
+const path = resolve(argv.at(-1));
+
+await write(
+  // stdout is a Blob
+  stdout,
+  // file(path) returns a Blob - https://developer.mozilla.org/en-US/docs/Web/API/Blob
+  file(path),
+);
+```
+
+Run this with `bun cat.js /path/to/big/file`.
+
+## Reading from standard input
+
+```ts
+// As of Bun v0.3.0, console is an AsyncIterable
+for await (const line of console) {
+  // line of text from stdin
+  console.log(line);
+}
+```
+
+## React SSR
+
+```js
+import { renderToReadableStream } from "react-dom/server";
+
+const dt = new Intl.DateTimeFormat();
+
+export default {
+  port: 3000,
+  async fetch(request: Request) {
+    return new Response(
+      await renderToReadableStream(
+        <html>
+          <head>
+            <title>Hello World</title>
+          </head>
+          <body>
+            <h1>Hello from React!</h1>
+            <p>The date is {dt.format(new Date())}</p>
+          </body>
+        </html>,
+      ),
+    );
+  },
+};
+```
+
+Write to stdout with `console.write`:
+
+```js
+// no trailing newline
+// works with strings and typed arrays
+console.write("Hello World!");
+```
+
+There are some more examples in the [examples](./examples) folder.
+
+PRs adding more examples are very welcome!
+
+## Fast paths for Web APIs
+
+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"));
+```