Docs tweaks (#2160)

* Tweaks * Add ecosystem. Add bunx. Flesh out install. * Tweaks * Add TS to installation * Tweaks * New readme * Write new readme * Tweak * Center header * Bun * tweaks * No dollar sign * Fix links * Update * Tweak
2026-02-02 15:08:46 +00:00 · 2023-02-24 16:33:53 -08:00
parent 1d85b5efa8
commit 1836250542
18 changed files with 444 additions and 5437 deletions
--- a/README.md
+++ b/README.md
--- a/docs/api/file-io.md
+++ b/docs/api/file-io.md
@@ -1,5 +1,5 @@
 {% callout %}
-**Note** — Bun also provides an [almost complete](/docs/runtime/nodejs) implementation of the Node.js `fs` module, documented [here](https://nodejs.org/api/fs.html). This page only documents Bun-native APIs.
+**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/runtime/nodejs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
 {% /callout %}

 Bun provides a set of optimized APIs for reading and writing files.
@@ -234,13 +234,7 @@ interface Bun {

  write(
    destination: string | number | FileBlob | URL,
-    input:
-      | string
-      | Blob
-      | ArrayBuffer
-      | SharedArrayBuffer
-      | TypedArray
-      | Response,
+    input: string | Blob | ArrayBuffer | SharedArrayBuffer | TypedArray | Response,
  ): Promise<number>;
 }

--- a/docs/api/http.md
+++ b/docs/api/http.md
@@ -1,10 +1,19 @@
 {% callout %}
-**Note** — Bun provides an [almost complete](/docs/runtime/nodejs#node_http) implementation of the Node.js [`http`](https://nodejs.org/api/http.html) and [`https`](https://nodejs.org/api/https.html) modules. This page only documents Bun-native APIs.
+**Note** — This page documents the `Bun.serve` API. This API is heavily optimized and represents the recommended way to build HTTP servers in Bun. Existing Node.js projectes may use Bun's [nearly complete](/docs/runtime/nodejs#node_http) implementation of the Node.js [`http`](https://nodejs.org/api/http.html) and [`https`](https://nodejs.org/api/https.html) modules.
 {% /callout %}

-## Start a server
+## Send a request

-`Bun.serve(options) => Server`
+Bun implements the Web `fetch` API for making HTTP requests. The `fetch` function is available in the global scope.
+
+```ts
+const response = await fetch("https://bun.sh/manifest.json");
+const result = (await response.json()) as any;
+console.log(result.icons[0].src);
+// => "/logo-square.jpg"
+```
+
+## Start a server

 Start an HTTP server in Bun with `Bun.serve`.

@@ -41,7 +50,7 @@ Bun.serve({
 });
 ```

-## Error handling
+### Error handling

 To activate development mode, set `development: true`. By default, development mode is _enabled_ unless `NODE_ENV` is `production`.

@@ -91,7 +100,7 @@ const server = Bun.serve({
 server.stop();
 ```

-## TLS
+### TLS

 Bun supports TLS out of the box, powered by [OpenSSL](https://www.openssl.org/). Enable TLS by passing in a value for `keyFile` and `certFile`; both are required to enable TLS. If needed, supply a `passphrase` to decrypt the `keyFile`.

@@ -120,7 +129,7 @@ Bun.serve({
 });
 ```

-## Hot reloading
+### Hot reloading

 Thus far, the examples on this page have used the explicit `Bun.serve` API. Bun also supports an alternate syntax.

@@ -142,7 +151,7 @@ $ bun --hot server.ts

 It's possible to configure hot reloading while using the explicit `Bun.serve` API; for details refer to [Runtime > Hot reloading](/docs/runtime/hot).

-## Streaming files
+### Streaming files

 To stream a file, return a `Response` object with a `BunFile` object as the body.

@@ -180,7 +189,7 @@ Bun.serve({
 });
 ```

-## Benchmarks
+### Benchmarks

 Below are Bun and Node.js implementations of a simple HTTP server that responds `Bun!` to each incoming `Request`.

@@ -223,7 +232,7 @@ The `Bun.serve` server can handle roughly 2.5x more requests per second than Nod

 {% image width="499" alt="image" src="https://user-images.githubusercontent.com/709451/162389032-fc302444-9d03-46be-ba87-c12bd8ce89a0.png" /%}

-## Reference
+### Reference

 {% details summary="See TypeScript definitions" %}

--- a/docs/api/websockets.md
+++ b/docs/api/websockets.md
@@ -1,4 +1,4 @@
-As of Bun v0.2.1, `Bun.serve()` supports server-side WebSockets, with on-the-fly compression, TLS support, and a Bun-native pubsub API.
+`Bun.serve()` supports server-side WebSockets, with on-the-fly compression, TLS support, and a Bun-native publish-subscribe API.

 {% callout %}

--- a/docs/cli/bunx.md
+++ b/docs/cli/bunx.md
@@ -0,0 +1,73 @@
+Use `bunx` to auto-install and run packages from `npm`. The `bunx` CLI will be auto-installed when you install `bun`.
+
+```bash
+$ bunx cowsay "Hello world!"
+```
+
+{% callout %}
+⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
+{% /callout %}
+
+Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
+
+```jsonc#package.json
+{
+  // ... other fields
+  "name": "my-cli",
+  "bin": {
+    "my-cli": "dist/index.js"
+  }
+}
+```
+
+These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`.
+
+```js#dist/index.js
+#!/usr/bin/env node
+
+console.log("Hello world!");
+```
+
+These executables can be run with `bunx`,
+
+```bash
+$ bunx my-cli
+```
+
+As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use.
+
+### Arguments and flags
+
+To pass additional command-line flags and arguments through to the executable, place them after the executable name.
+
+```bash
+$ bunx my-cli --foo bar
+```
+
+### Shebangs
+
+By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag.
+
+```bash
+$ bunx --bun my-cli
+```
+
+{% callout %}
+**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable.
+
+```bash
+$ bunx --bun my-cli # good
+$ bunx my-cli --bun # bad
+```
+
+{% /callout %}
+
+## Environment variables
+
+Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:
+
+1. `.env.local` (first)
+2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
+3. `.env`
+
+To debug environment variables, run `bun run env` to view a list of resolved environment variables.
--- a/docs/cli/create.md
+++ b/docs/cli/create.md
@@ -188,9 +188,7 @@ When cloning a template, `bun create` will automatically remove the `"bun-create

 {% /table %}

-### How `bun create` works
-
-{% details summary="View details" %}
+{% details summary="How `bun create` works" %}

 When you run `bun create ${template} ${destination}`, here’s what happens:

--- a/docs/cli/install.md
+++ b/docs/cli/install.md
@@ -1,6 +1,4 @@
-The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`.
-
-It can be be used as a drop-in replacement for these tools, _regardless of whether you're using Bun's runtime_.
+The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project.

 {% callout %}

@@ -86,7 +84,7 @@ dryRun = false

 {% /details %}

-## Adding packages
+## Add and remove packages

 To add or remove a particular package:

@@ -149,6 +147,27 @@ To view a complete list of options for a given command:
 $ bun add --help
 ```

+## Git dependencies
+
+To add a dependency from a git repository:
+
+```bash
+$ bun install git@github.com:moment/moment.git
+```
+
+Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
+
+```json
+{
+  "dependencies": {
+    "dayjs": "git+https://github.com/iamkun/dayjs.git",
+    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
+    "moment": "git@github.com:moment/moment.git",
+    "zod": "github:colinhacks/zod"
+  }
+}
+```
+
 ## Global cache

 All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
@@ -328,7 +347,7 @@ registry = { url = "https://registry.npmjs.org", token = "123456" }
 registry = "https://username:password@registry.npmjs.org"
 ```

-To configure organization-scoped registries:
+To configure a private registry scoped to a particular organization:

 ```toml
 [install.scopes]
@@ -342,3 +361,85 @@ To configure organization-scoped registries:
 # registry with token
 "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
 ```
+
+## Linking and unlinking
+
+Use `bun link` in a local directory to register the current package as a "linkable" package.
+
+```bash
+$ cd /path/to/cool-pkg
+$ cat package.json
+{
+  "name": "cool-pkg",
+  "version": "1.0.0"
+}
+$ bun link
+bun link v0.5.7 (7416672e)
+Success! Registered "cool-pkg"
+
+To use cool-pkg in a project, run:
+  bun link cool-pkg
+
+Or add it in dependencies in your package.json file:
+  "cool-pkg": "link:cool-pkg"
+```
+
+This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
+
+```bash
+$ cd /path/to/my-app
+$ bun link cool-pkg
+```
+
+This will add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
+    "dependencies": {
+     "cool-pkg": "link:cool-pkg"
+    }
+  }
+```
+
+## Utilities
+
+The `bun pm` command group provides a set of utilities for working with Bun's package manager.
+
+To print the path to the `bin` directory for the local project:
+
+```bash
+$ bun pm bin
+/path/to/current/project/node_modules/.bin
+```
+
+To get the path to the global `bin` directory:
+
+```bash
+$ bun pm bin
+<$HOME>/.bun/bin
+```
+
+To print a list of packages installed in the current project and their resolved versions, excluding their dependencies. Use the `--all` flag to print the entire tree, including all nth-order dependencies.
+
+```bash
+/path/to/project node_modules (5)
+├── eslint@8.33.0
+├── react@18.2.0
+├── react-dom@18.2.0
+├── typescript@4.8.4
+└── zod@3.20.1
+```
+
+To print the path to Bun's global module cache:
+
+```bash
+$ bun pm cache
+```
+
+To clear Bun's global module cache:
+
+```bash
+$ bun pm cache rm
+```
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -1,6 +1,6 @@
 The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin).

-## Run a file
+## Running a file

 {% callout %}
 Compare to `node <file>`
@@ -25,7 +25,7 @@ Billie Eilish

 If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules).

-## Run a package script
+## Running a package script

 {% note %}
 Compare to `npm run <script>` or `yarn <script>`
@@ -80,77 +80,3 @@ quickstart scripts:
 ```

 Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself.
-
-## Run an executable
-
-{% callout %}
-Compare to `npx <command>`
-{% /callout %}
-
-Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
-
-```jsonc#package.json
-{
-  // ... other fields
-  "name": "my-cli",
-  "bin": {
-    "my-cli": "dist/index.js"
-  }
-}
-```
-
-These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`.
-
-```js#dist/index.js
-#!/usr/bin/env node
-
-console.log("Hello world!");
-```
-
-These executables can be run with `bunx`, Bun's equivalent of `npx`.
-
-{% callout %}
-⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
-{% /callout %}
-
-```bash
-$ bunx my-cli
-```
-
-As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use.
-
-### Arguments and flags
-
-To pass additional command-line flags and arguments through to the executable:
-
-```bash
-$ bunx my-cli --foo bar
-```
-
-### Shebangs
-
-By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag.
-
-```bash
-$ bunx --bun my-cli
-```
-
-{% callout %}
-**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable.
-
-```bash
-$ bunx --bun my-cli # good
-$ bunx my-cli --bun # bad
-```
-
-{% /callout %}
-
-## Environment variables
-
-Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:
-
-1. `.env.local` (first)
-2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
-3. `.env`
-
-To debug environment variables, run `bun run env` to view a list of resolved environment variables.
--- a/docs/cli/test.md
+++ b/docs/cli/test.md
@@ -1,9 +1,23 @@
 Bun ships with a built-in test runner.

 ```bash
-$ bun wiptest
+$ bun test
 ```

+Tests are written in JavaScript or TypeScript with a Jest-like API.
+
+```ts#math.test.ts
+import { expect, test } from "bun:test";
+
+test("2 + 2", () => {
+  expect(2 + 2).toBe(4);
+});
+```
+
+It's fast.
+
+{% image src="/images/buntest.jpeg" caption="Bun runs 266 React SSR tests faster than Jest can print its version number." /%}
+
 The runner recursively searches the working directory for files that match the following patterns:

 - `*.test.{js|jsx|ts|tsx}`
@@ -11,10 +25,10 @@ The runner recursively searches the working directory for files that match the f
 - `*.spec.{js|jsx|ts|tsx}`
 - `*_spec.{js|jsx|ts|tsx}`

-You can filter the set of tests to run by passing additional positional arguments to `wiptest`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
+You can filter the set of tests to run by passing additional positional arguments to `bun test`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.

 ```bash
-$ bun wiptest <filter> <filter> ...
+$ bun test <filter> <filter> ...
 ```

 <!--
@@ -33,13 +47,13 @@ Consider the following directory structure:
 To run both `a.test.ts` files:

 ```
-$ bun wiptest a
+$ bun test a
 ```

 To run all tests in the `foo` directory:

 ```
-$ bun wiptest foo
+$ bun test foo
 ```

 Any test file in the directory with an _absolute path_ that contains one of the targets will run. Glob patterns are not yet supported. -->
@@ -112,7 +126,7 @@ afterEach(() => {
 // tests...
 ```

-Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the *scope* is the current file; in a `describe` block, the scope is the block itself.
+Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the _scope_ is the current file; in a `describe` block, the scope is the block itself.

 ```ts
 import { expect, test, beforeAll, afterAll } from "bun:test";
--- a/docs/ecosystem/express.md
+++ b/docs/ecosystem/express.md
@@ -0,0 +1,37 @@
+Projects that use Express and other major Node.js HTTP libraries should work out of the box. 
+
+{% callout %}
+If you run into bugs, [please file an issue](https://bun.sh/issues) *in Bun's repo*, not the library. It is Bun's responsibility to address Node.js compatibility issues.
+{% /callout %}
+
+```ts
+import express from "express";
+
+const app = express();
+const port = 8080;
+
+app.get("/", (req, res) => {
+  res.send("Hello World!");
+});
+
+app.listen(port, () => {
+  console.log(`Listening on port ${port}...`);
+});
+```
+
+Bun implements the [`node:http`](https://nodejs.org/api/http.html) and [`node:https`](https://nodejs.org/api/https.html) modules that these libraries rely on. These modules can also be used directly, though [`Bun.serve`](/docs/api/http) is recommended for most use cases.
+
+{% callout %}
+**Note** — Refer to the [Runtime > Node.js APIs](/docs/runtime/nodejs#node_http) page for more detailed compatibility information.
+{% /callout %}
+
+```ts
+import * as http from "node:http";
+
+http
+  .createServer(function (req, res) {
+    res.write("Hello World!");
+    res.end();
+  })
+  .listen(8080);
+```
--- a/docs/ecosystem/nodejs.md
+++ b/docs/ecosystem/nodejs.md
@@ -33,7 +33,7 @@ This page is updated regularly to reflect compatibility status of the latest ver

 - {% anchor id="node_child_process" %} [`node:child_process`](https://nodejs.org/api/child_process.html) {% /anchor %}
 - 🟡
- Missing IPC, `Stream` stdio, `proc.gid`, `proc.uid`, advanced serialization
+- Missing IPC, `Stream` stdio, `proc.gid`, `proc.uid`, advanced serialization.

 ---

--- a/docs/ecosystem/react.md
+++ b/docs/ecosystem/react.md
@@ -0,0 +1,46 @@
+Bun supports `.jsx` and `.tsx` files out of the box. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
+
+```ts#react.tsx
+function Component(props: {message: string}) {
+  return (
+    <body>
+      <h1 style={{fontSize: 'red'}}>{props.message}</h1>
+    </body>
+  );
+}
+
+console.log(<Component />);
+```
+
+Bun implements special logging for JSX to make debugging easier.
+
+```bash
+$ bun run react.tsx
+<Component message="Hello world!" />
+```
+
+To server-side render (SSR) React in an [HTTP server](/docs/api/http):
+
+```tsx#ssr.tsx
+import {renderToReadableStream} from 'react-dom/server';
+
+function Component(props: {message: string}) {
+  return (
+    <body>
+      <h1 style={{fontSize: 'red'}}>{props.message}</h1>
+    </body>
+  );
+}
+
+Bun.serve({
+  port: 4000,
+  async fetch() {
+    const stream = await renderToReadableStream(
+      <Component message="Hello from server!" />
+    );
+    return new Response(stream, {
+      headers: {'Content-Type': 'text/html'},
+    });
+  },
+});
+```
--- a/docs/ecosystem/typescript.md
+++ b/docs/ecosystem/typescript.md
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,11 +1,22 @@
-Bun is an all-in-one toolkit for building JavaSript and TypeScript apps. It ships as a single executable called `bun`.
+Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called `bun`.

-At its core is the _Bun runtime_, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Zig and powered by JavaScriptCore under the hood. Use `bun run <file>` to execute JavaScript and TypeScript files with Bun.
+At its core is the _Bun runtime_, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.

-The `bun` command-line tool also implements an npm-compatible package manager, test runner, and bundler, all written in Zig and designed for speed. Use `bun` to speed up your development workflow, even if you aren't using the runtime.
+```bash
+$ bun run index.tsx  # TS and JSX supported out of the box
+```
+
+The `bun` command-line tool also implements a test runner, script runner, and Node.js-compatible package manager, all significantly faster than existing tools and usable in existing Node.js projects with little to no changes necessary.
+
+```bash
+$ bun test                      # run tests
+$ bun run start                 # run the `start` script
+$ bun install <pkg>             # install a package
+$ bunx cowsay "Hello, world!"   # execute a package
+```

 {% callout type="note" %}
-**Bun is not yet ready for use in production**. Join the [Discord](https://bun.sh/discord) and watch the [GitHub repository](https://github.com/oven-sh/bun) to keeps tabs on future releases.
+**Bun is still under development.** Use it to speed up your development workflows or run simpler production code in resource-constrained environments like serverless functions. We're working on more complete Node.js compatibility and integration with existing frameworks. Join the [Discord](https://bun.sh/discord) and watch the [GitHub repository](https://github.com/oven-sh/bun) to keeps tabs on future releases.
 {% /callout %}

 ### Get started
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -93,6 +93,26 @@ $ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
 this is some output
 ``` -->

+## TypeScript
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `bun-types`.
+
+```sh
+$ bun add -d bun-types # dev dependency
+```
+
+Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`:
+
+```json-diff
+  {
+    "compilerOptions": {
+     "types": ["bun-types"]
+    }
+  }
+```
+
+Refer to [Ecosystem > TypeScript](/docs/ecosystem/typescript) for a complete guide to TypeScript support in Bun.
+
 ## Completions

 Shell auto-completion should be configured automatically when Bun is installed.
--- a/docs/nav.ts
+++ b/docs/nav.ts
@@ -26,13 +26,14 @@ export default {
    page("index", "What is Bun?"),
    page("installation", "Installation"),
    page("quickstart", "Quickstart"),
-    page("typescript", "TypeScript"),
+    // page("typescript", "TypeScript"),

    divider("CLI"),
    page("cli/run", "`bun run`"),
    page("cli/install", "`bun install`"),
    page("cli/test", "`bun test`"),
    page("cli/create", "`bun create`"),
+    page("cli/bunx", "`bunx`"),
    // page("bundler", "Bundler"),
    // page("cli/bun-install", "`bun install`"),
    // page("cli/bun-create", "`bun create`"),
@@ -50,7 +51,14 @@ export default {
    page("runtime/hot", "Hot reloading"),
    // page("runtime/loaders", "Loaders"),
    page("runtime/plugins", "Plugins"),
-    page("runtime/nodejs", "Node.js APIs"),
+    // page("runtime/nodejs", "Node.js APIs"),
+
+    divider("Ecosystem"),
+    page("ecosystem/nodejs", "Node.js"),
+    page("ecosystem/typescript", "TypeScript"),
+    page("ecosystem/react", "React"),
+    page("ecosystem/express", "Express"),
+    page("ecosystem/awesome", "Awesome Bun"),

    divider("API"),
    page("api/http", "HTTP"), // "`Bun.serve`"),
--- a/docs/project/developing.md
+++ b/docs/project/developing.md
@@ -3,7 +3,7 @@ Configuring a development environment for Bun usually takes 30-90 minutes depend

 ## Linux/Windows

-The best way to build Bun on Linux and Windows is with the official [Dev Container](https://containers.dev). It ships with Zig, JavaScriptCore, Zig Language Server, `vscode-zig`, and more pre-installed on an instance of Ubuntu.
+The best way to build Bun on Linux and Windows is with the official [Dev Container](https://containers.dev). It ships with Zig, JavaScriptCore, Zig Language Server, and more pre-installed on an instance of Ubuntu.

 {% image src="https://user-images.githubusercontent.com/709451/147319227-6446589c-a4d9-480d-bd5b-43037a9e56fd.png" /%}

@@ -204,21 +204,6 @@ Certain modules like `node:fs`, `node:path`, `node:stream`, and `bun:sqlite` are

 While Bun is in beta, you can modify them at runtime in release builds via the environment variable `BUN_OVERRIDE_MODULE_PATH`. When set, Bun will look in the override directory for `<name>.exports.js` before checking the files from `src/bun.js` (which are now baked in to the binary). This lets you test changes to the ESM modules without needing to re-compile Bun.

-## `vscode-zig`
-
-{% callout %}
-**Note** — This is automatically installed on the devcontainer.
-{% /callout %}
-
-We maintain a fork of the `vscode-zig` extension that adds a `Run test` and a `Debug test` button into the dev environment. To install it:
-
-```bash
-$ curl -L https://github.com/Jarred-Sumner/vscode-zig/releases/download/fork-v1/zig-0.2.5.vsix > vscode-zig.vsix
-$ code --install-extension vscode-zig.vsix
-```
-
-{% image src="https://pbs.twimg.com/media/FBZsKHlUcAYDzm5?format=jpg&name=large" href="https://github.com/jarred-sumner/vscode-zig" /%}
-
 ## Troubleshooting

 If you encounter `error: the build command failed with exit code 9` during the build process, this means you ran out of memory or swap. Bun currently needs about 22 GB of RAM to compile.
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -78,8 +78,7 @@ $ bun run start
 ```

 {% callout %}
-⚡️ **Performance** — With Bun's fast startup times, this script executes in roughly `6ms`.
-By contrast `npm run` adds roughly `170ms` of overhead when executing scripts.
+⚡️ **Performance** — `bun run` is roughly 28x faster than `npm run` (6ms vs 170ms of overhead).
 {% /callout %}

 ## Install a package