## Summary
Updates documentation for all major features and changes introduced in
Bun v1.3.2 blog post.
## Changes
### Package Manager
- ✅ Document `configVersion` system for controlling default linker
behavior
- ✅ Clarify that "existing projects (made pre-v1.3.2)" use hoisted
installs for backward compatibility
- ✅ Add smart postinstall script optimization with environment variable
flags
- ✅ Document improved Git dependency resolution with HTTP tarball
optimization
- ✅ Add `bun list` alias for `bun pm ls`
### Testing
- ✅ Document new `onTestFinished` lifecycle hook with simple example
- ✅ Add to lifecycle hooks table in test documentation
### Runtime & Performance
- ✅ Add CPU profiling with `--cpu-prof` flag documentation
- ✅ Place after memory usage section for better flow
### WebSockets
- ✅ Add `subscriptions` getter to existing pub/sub example
- ✅ Add TypeScript reference for the subscriptions property
## Documentation Improvements
All documentation now consistently:
- Uses "made pre-v1.3.2" to clarify existing project behavior
- Simplifies default linker explanations with clear references to
`/docs/pm/isolated-installs`
- Uses `/docs/pm/isolated-installs` for all internal references
- Avoids confusing technical details in favor of user-friendly summaries
## Files Modified
- `docs/guides/install/add-git.mdx` - Added GitHub tarball optimization
note
- `docs/pm/cli/install.mdx` - Added installation strategies and smart
postinstall docs
- `docs/pm/cli/pm.mdx` - Added bun list alias
- `docs/pm/isolated-installs.mdx` - Updated default behavior section
with configVersion table
- `docs/project/benchmarking.mdx` - Added CPU profiling section
- `docs/runtime/bunfig.mdx` - Clarified install.linker defaults
- `docs/runtime/http/websockets.mdx` - Added subscriptions to example
and TypeScript interface
- `docs/test/lifecycle.mdx` - Added onTestFinished hook documentation
## Diff
````diff
diff --git a/docs/guides/install/add-git.mdx b/docs/guides/install/add-git.mdx
index 70950e1a63..7f8f3c8d81 100644
--- a/docs/guides/install/add-git.mdx
+++ b/docs/guides/install/add-git.mdx
@@ -33,6 +33,8 @@ bun add git@github.com:lodash/lodash.git
bun add github:colinhacks/zod
```
+**Note:** GitHub dependencies download via HTTP tarball when possible for faster installation.
+
---
See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/pm/cli/install.mdx b/docs/pm/cli/install.mdx
index 7affb62646..dde268b7e5 100644
--- a/docs/pm/cli/install.mdx
+++ b/docs/pm/cli/install.mdx
@@ -88,6 +88,13 @@ Lifecycle scripts will run in parallel during installation. To adjust the maximu
bun install --concurrent-scripts 5
```
+Bun automatically optimizes postinstall scripts for popular packages (like `esbuild`, `sharp`, etc.) by determining which scripts need to run. To disable these optimizations:
+
+```bash terminal icon="terminal"
+BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
+BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install
+```
+
---
## Workspaces
@@ -231,7 +238,7 @@ Bun supports installing dependencies from Git, GitHub, and local or remotely-hos
Bun supports two package installation strategies that determine how dependencies are organized in `node_modules`:
-### Hoisted installs (default for single projects)
+### Hoisted installs
The traditional npm/Yarn approach that flattens dependencies into a shared `node_modules` directory:
@@ -249,7 +256,15 @@ bun install --linker isolated
Isolated installs create a central package store in `node_modules/.bun/` with symlinks in the top-level `node_modules`. This ensures packages can only access their declared dependencies.
-For complete documentation on isolated installs, refer to [Package manager > Isolated installs](/pm/isolated-installs).
+### Default strategy
+
+The default linker strategy depends on whether you're starting fresh or have an existing project:
+
+- **New workspaces/monorepos**: `isolated` (prevents phantom dependencies)
+- **New single-package projects**: `hoisted` (traditional npm behavior)
+- **Existing projects (made pre-v1.3.2)**: `hoisted` (preserves backward compatibility)
+
+The default is controlled by a `configVersion` field in your lockfile. For a detailed explanation, see [Package manager > Isolated installs](/docs/pm/isolated-installs).
---
@@ -319,8 +334,7 @@ dryRun = false
concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
# installation strategy: "hoisted" or "isolated"
-# default: "hoisted" (for single-project projects)
-# default: "isolated" (for monorepo projects)
+# default varies by project type - see /docs/pm/isolated-installs
linker = "hoisted"
diff --git a/docs/pm/cli/pm.mdx b/docs/pm/cli/pm.mdx
index fc297753d3..9c8faa7da1 100644
--- a/docs/pm/cli/pm.mdx
+++ b/docs/pm/cli/pm.mdx
@@ -115,6 +115,8 @@ To print a list of installed dependencies in the current project and their resol
```bash terminal icon="terminal"
bun pm ls
+# or
+bun list
```
```txt
@@ -130,6 +132,8 @@ To print all installed dependencies, including nth-order dependencies.
```bash terminal icon="terminal"
bun pm ls --all
+# or
+bun list --all
```
```txt
diff --git a/docs/pm/isolated-installs.mdx b/docs/pm/isolated-installs.mdx
index 73c6748b15..17afe02fe1 100644
--- a/docs/pm/isolated-installs.mdx
+++ b/docs/pm/isolated-installs.mdx
@@ -5,7 +5,7 @@ description: "Strict dependency isolation similar to pnpm's approach"
Bun provides an alternative package installation strategy called **isolated installs** that creates strict dependency isolation similar to pnpm's approach. This mode prevents phantom dependencies and ensures reproducible, deterministic builds.
-This is the default installation strategy for monorepo projects.
+This is the default installation strategy for **new** workspace/monorepo projects (with `configVersion = 1` in the lockfile). Existing projects continue using hoisted installs unless explicitly configured.
## What are isolated installs?
@@ -43,8 +43,23 @@ linker = "isolated"
### Default behavior
-- For monorepo projects, Bun uses the **isolated** installation strategy by default.
-- For single-project projects, Bun uses the **hoisted** installation strategy by default.
+The default linker strategy depends on your project's lockfile `configVersion`:
+
+| `configVersion` | Using workspaces? | Default Linker |
+| --------------- | ----------------- | -------------- |
+| `1` | ✅ | `isolated` |
+| `1` | ❌ | `hoisted` |
+| `0` | ✅ | `hoisted` |
+| `0` | ❌ | `hoisted` |
+
+**New projects**: Default to `configVersion = 1`. In workspaces, v1 uses the isolated linker by default; otherwise it uses hoisted linking.
+
+**Existing Bun projects (made pre-v1.3.2)**: If your existing lockfile doesn't have a version yet, Bun sets `configVersion = 0` when you run `bun install`, preserving the previous hoisted linker default.
+
+**Migrations from other package managers**:
+
+- From pnpm: `configVersion = 1` (using isolated installs in workspaces)
+- From npm or yarn: `configVersion = 0` (using hoisted installs)
You can override the default behavior by explicitly specifying the `--linker` flag or setting it in your configuration file.
diff --git a/docs/project/benchmarking.mdx b/docs/project/benchmarking.mdx
index 1263a06729..2ab8bcafc8 100644
--- a/docs/project/benchmarking.mdx
+++ b/docs/project/benchmarking.mdx
@@ -216,3 +216,26 @@ numa nodes: 1
elapsed: 0.068 s
process: user: 0.061 s, system: 0.014 s, faults: 0, rss: 57.4 MiB, commit: 64.0 MiB
```
+
+## CPU profiling
+
+Profile JavaScript execution to identify performance bottlenecks with the `--cpu-prof` flag.
+
+```sh terminal icon="terminal"
+bun --cpu-prof script.js
+```
+
+This generates a `.cpuprofile` file you can open in Chrome DevTools (Performance tab → Load profile) or VS Code's CPU profiler.
+
+### Options
+
+```sh terminal icon="terminal"
+bun --cpu-prof --cpu-prof-name my-profile.cpuprofile script.js
+bun --cpu-prof --cpu-prof-dir ./profiles script.js
+```
+
+| Flag | Description |
+| ---------------------------- | -------------------- |
+| `--cpu-prof` | Enable profiling |
+| `--cpu-prof-name <filename>` | Set output filename |
+| `--cpu-prof-dir <dir>` | Set output directory |
diff --git a/docs/runtime/bunfig.mdx b/docs/runtime/bunfig.mdx
index 91005c1607..5b7fe49823 100644
--- a/docs/runtime/bunfig.mdx
+++ b/docs/runtime/bunfig.mdx
@@ -497,9 +497,9 @@ print = "yarn"
### `install.linker`
-Configure the default linker strategy. Default `"hoisted"` for single-project projects, `"isolated"` for monorepo projects.
+Configure the linker strategy for installing dependencies. Defaults to `"isolated"` for new workspaces, `"hoisted"` for new single-package projects and existing projects (made pre-v1.3.2).
-For complete documentation refer to [Package manager > Isolated installs](/pm/isolated-installs).
+For complete documentation refer to [Package manager > Isolated installs](/docs/pm/isolated-installs).
```toml title="bunfig.toml" icon="settings"
[install]
diff --git a/docs/runtime/http/websockets.mdx b/docs/runtime/http/websockets.mdx
index b33f37c29f..174043200d 100644
--- a/docs/runtime/http/websockets.mdx
+++ b/docs/runtime/http/websockets.mdx
@@ -212,6 +212,9 @@ const server = Bun.serve({
// this is a group chat
// so the server re-broadcasts incoming message to everyone
server.publish("the-group-chat", `${ws.data.username}: ${message}`);
+
+ // inspect current subscriptions
+ console.log(ws.subscriptions); // ["the-group-chat"]
},
close(ws) {
const msg = `${ws.data.username} has left the chat`;
@@ -393,6 +396,7 @@ interface ServerWebSocket {
readonly data: any;
readonly readyState: number;
readonly remoteAddress: string;
+ readonly subscriptions: string[];
send(message: string | ArrayBuffer | Uint8Array, compress?: boolean): number;
close(code?: number, reason?: string): void;
subscribe(topic: string): void;
diff --git a/docs/test/lifecycle.mdx b/docs/test/lifecycle.mdx
index 6427175df6..3837f0e948 100644
--- a/docs/test/lifecycle.mdx
+++ b/docs/test/lifecycle.mdx
@@ -6,11 +6,12 @@ description: "Learn how to use beforeAll, beforeEach, afterEach, and afterAll li
The test runner supports the following lifecycle hooks. This is useful for loading test fixtures, mocking data, and configuring the test environment.
| Hook | Description |
-| ------------ | --------------------------- |
+| ---------------- | ---------------------------------------------------------- |
| `beforeAll` | Runs once before all tests. |
| `beforeEach` | Runs before each test. |
| `afterEach` | Runs after each test. |
| `afterAll` | Runs once after all tests. |
+| `onTestFinished` | Runs after a single test finishes (after all `afterEach`). |
## Per-Test Setup and Teardown
@@ -90,6 +91,23 @@ describe("test group", () => {
});
```
+### `onTestFinished`
+
+Use `onTestFinished` to run a callback after a single test completes. It runs after all `afterEach` hooks.
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, onTestFinished } from "bun:test";
+
+test("cleanup after test", () => {
+ onTestFinished(() => {
+ // runs after all afterEach hooks
+ console.log("test finished");
+ });
+});
+```
+
+Not supported in concurrent tests; use `test.serial` instead.
+
## Global Setup and Teardown
To scope the hooks to an entire multi-file test run, define the hooks in a separate file.
````
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Michael H <git@riskymh.dev>
Co-authored-by: Lydia Hallie <lydiajuliettehallie@gmail.com>
* Make some things sync on windows
* WIP
* WIP
* remove uses to uv_default_loop
* remove a compiler warning on windows
* edfghjk
* Windows build fixes
* Fixup
* bundows
* Add quotes
* Fix --cwd arg on Windows
* comment
* move this up
* Fix some tests
* `mv` tests pass
* spawn.test passes again
* Allow .sh file extension for Windows
* Unmark failing tests
* env test pass
* windows
* Fix some tests
* Update ProcessBindingTTYWrap.cpp
* Update CMakeLists.txt
* Set tmpdir
* Make it 5s on windows
* Fixup
* Fixup
* Update ProcessBindingTTYWrap.cpp
---------
Co-authored-by: Jarred Sumner <709451+Jarred-Sumner@users.noreply.github.com>
Co-authored-by: dave caruso <me@paperdave.net>
* Add openSUSE Tumbleweed to the list of supported Linux distributions in CMakeLists.txt
* openSUSE Tumbleweed setup
* Revert "Add openSUSE Tumbleweed to the list of supported Linux distributions in CMakeLists.txt"
This reverts commit 93faed88a1.
---------
Co-authored-by: nellfs <nellfs@localhost.localdomain>
* Update contributing.md
Added documentation for the installation of the perl Math::BigInt module
* Update contributing.md
merged the fedora perl math bigint module with the other dependencies
* Add brotli test
* Check if we can use brotli
* vendor brotli
* Update .gitattributes
* Brotli is now always available
* Update licensing.md
---------
Co-authored-by: Jarred Sumner <709451+Jarred-Sumner@users.noreply.github.com>
* fix(win/upgrade): do not show powershell expand-archive info while upgrading
* start working bun run
* experiment: `bun.new`
* you can now bun run
* Update src/install/install.zig
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
* Update src/install/install.zig
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
* stuff
* fix stuff
* fix this
* farther but not really
* sadfs
* path hell
not sure how much worse or better this makes things. its a mess. windows path handlign is a mess aaaaaaaaaaaaaaaa
* path.resolve bs
* remove old build system stuff from pr
* a
* fix some path.parse/join cases
* path closer not perfect
* normalize and join tests tests done
* paths
* implement path.relative
* ,
* stuff
* assert
* fix compile
* hate
* the code isnt great
* stuff
* housekeeping for build system
* blah
* explain windows sitaution in docs
* some progress? not much though
* zig compiler crashes here
* fix
* yippee
* ok
* a
* ala wala
* fix builds on stuff
* clean
* the tests now run
* a
* aa
* dedupe uv event loop
* fix fs test accuracy
* stuff
* [autofix.ci] apply automated fixes
* huge updat e
* [autofix.ci] apply automated fixes
* url
* [autofix.ci] apply automated fixes
* start windows spawnSync
* [autofix.ci] apply automated fixes
* add --webkit for update submodules
* add better err message for `bun setup`
* fix unix platform build
* .
* [autofix.ci] apply automated fixes
* un-upgrade libarchive
* z
* asdfghj
* wrk
* todo -> panic
* ok
* a
* [autofix.ci] apply automated fixes
* fix build scripts l ol
* dfghj
* fa
* [autofix.ci] apply automated fixes
* aaaa
* a
* l
* [autofix.ci] apply automated fixes
* more logs
* [autofix.ci] apply automated fixes
* j
* fix init_command
* CORE DUMP HELL
* i swear im being pranked by the github actions gods
* fadsjkfdshjkhjkdfsahjkdfshjksdafjkhhjkfdsahfsdkjhfsdjkahf
* thanks IAS
* this is the correct fix
* personal review
* ddisablbe these
* revisions!
* ok
* fix submodule
* stuff
* fix libarchive
* [autofix.ci] apply automated fixes
* stuff
* [autofix.ci] apply automated fixes
* a
* fix addressToJS on windows
* make dns async again
* dx: add flag to update submodules ps1 to clone webkit
* dns error case for libuv
* dx improvements on windows
* newline
* obvious fix
* install steps
* extra note
* fix fs test
* Update building-windows.md
* fix builtins bundler to support \r\n line endnigs
* better
* some windows stuff
* a
* a
* a
* aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
* [autofix.ci] apply automated fixes
* bunfile text works
* fix build on the mac
* hellooooooooooo
* install steps
* ci for baseline?
* fix
* aaa
* wow
* install script revamp
* bug
* OK
* ok
* aaaaaaaaaaaaaa
* okay
* fix the node test runner lol
* fix napi stuff
---------
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: cirospaciari <ciro.spaciai@gmail.com>
Co-authored-by: Dylan Conway <35280289+dylan-conway@users.noreply.github.com>
