mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
b876938f6d
## 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>
221 lines
8.4 KiB
Plaintext
221 lines
8.4 KiB
Plaintext
---
|
|
title: "Isolated installs"
|
|
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 **new** workspace/monorepo projects (with `configVersion = 1` in the lockfile). Existing projects continue using hoisted installs unless explicitly configured.
|
|
|
|
## What are isolated installs?
|
|
|
|
Isolated installs create a non-hoisted dependency structure where packages can only access their explicitly declared dependencies. This differs from the traditional "hoisted" installation strategy used by npm and Yarn, where dependencies are flattened into a shared `node_modules` directory.
|
|
|
|
### Key benefits
|
|
|
|
- **Prevents phantom dependencies** — Packages cannot accidentally import dependencies they haven't declared
|
|
- **Deterministic resolution** — Same dependency tree regardless of what else is installed
|
|
- **Better for monorepos** — Workspace isolation prevents cross-contamination between packages
|
|
- **Reproducible builds** — More predictable resolution behavior across environments
|
|
|
|
## Using isolated installs
|
|
|
|
### Command line
|
|
|
|
Use the `--linker` flag to specify the installation strategy:
|
|
|
|
```bash terminal icon="terminal"
|
|
# Use isolated installs
|
|
bun install --linker isolated
|
|
|
|
# Use traditional hoisted installs
|
|
bun install --linker hoisted
|
|
```
|
|
|
|
### Configuration file
|
|
|
|
Set the default linker strategy in your `bunfig.toml` or globally in `$HOME/.bunfig.toml`:
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[install]
|
|
linker = "isolated"
|
|
```
|
|
|
|
### Default behavior
|
|
|
|
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.
|
|
|
|
## How isolated installs work
|
|
|
|
### Directory structure
|
|
|
|
Instead of hoisting dependencies, isolated installs create a two-tier structure:
|
|
|
|
```bash tree layout of node_modules icon="list-tree"
|
|
node_modules/
|
|
├── .bun/ # Central package store
|
|
│ ├── package@1.0.0/ # Versioned package installations
|
|
│ │ └── node_modules/
|
|
│ │ └── package/ # Actual package files
|
|
│ ├── @scope+package@2.1.0/ # Scoped packages (+ replaces /)
|
|
│ │ └── node_modules/
|
|
│ │ └── @scope/
|
|
│ │ └── package/
|
|
│ └── ...
|
|
└── package-name -> .bun/package@1.0.0/node_modules/package # Symlinks
|
|
```
|
|
|
|
### Resolution algorithm
|
|
|
|
1. **Central store** — All packages are installed in `node_modules/.bun/package@version/` directories
|
|
2. **Symlinks** — Top-level `node_modules` contains symlinks pointing to the central store
|
|
3. **Peer resolution** — Complex peer dependencies create specialized directory names
|
|
4. **Deduplication** — Packages with identical package IDs and peer dependency sets are shared
|
|
|
|
### Workspace handling
|
|
|
|
In monorepos, workspace dependencies are handled specially:
|
|
|
|
- **Workspace packages** — Symlinked directly to their source directories, not the store
|
|
- **Workspace dependencies** — Can access other workspace packages in the monorepo
|
|
- **External dependencies** — Installed in the isolated store with proper isolation
|
|
|
|
## Comparison with hoisted installs
|
|
|
|
| Aspect | Hoisted (npm/Yarn) | Isolated (pnpm-like) |
|
|
| ------------------------- | ------------------------------------------ | --------------------------------------- |
|
|
| **Dependency access** | Packages can access any hoisted dependency | Packages only see declared dependencies |
|
|
| **Phantom dependencies** | ❌ Possible | ✅ Prevented |
|
|
| **Disk usage** | ✅ Lower (shared installs) | ✅ Similar (uses symlinks) |
|
|
| **Determinism** | ❌ Less deterministic | ✅ More deterministic |
|
|
| **Node.js compatibility** | ✅ Standard behavior | ✅ Compatible via symlinks |
|
|
| **Best for** | Single projects, legacy code | Monorepos, strict dependency management |
|
|
|
|
## Advanced features
|
|
|
|
### Peer dependency handling
|
|
|
|
Isolated installs handle peer dependencies through sophisticated resolution:
|
|
|
|
```bash tree layout of node_modules icon="list-tree"
|
|
# Package with peer dependencies creates specialized paths
|
|
node_modules/.bun/package@1.0.0_react@18.2.0/
|
|
```
|
|
|
|
The directory name encodes both the package version and its peer dependency versions, ensuring each unique combination gets its own installation.
|
|
|
|
### Backend strategies
|
|
|
|
Bun uses different file operation strategies for performance:
|
|
|
|
- **Clonefile** (macOS) — Copy-on-write filesystem clones for maximum efficiency
|
|
- **Hardlink** (Linux/Windows) — Hardlinks to save disk space
|
|
- **Copyfile** (fallback) — Full file copies when other methods aren't available
|
|
|
|
### Debugging isolated installs
|
|
|
|
Enable verbose logging to understand the installation process:
|
|
|
|
```bash terminal icon="terminal"
|
|
bun install --linker isolated --verbose
|
|
```
|
|
|
|
This shows:
|
|
|
|
- Store entry creation
|
|
- Symlink operations
|
|
- Peer dependency resolution
|
|
- Deduplication decisions
|
|
|
|
## Troubleshooting
|
|
|
|
### Compatibility issues
|
|
|
|
Some packages may not work correctly with isolated installs due to:
|
|
|
|
- **Hardcoded paths** — Packages that assume a flat `node_modules` structure
|
|
- **Dynamic imports** — Runtime imports that don't follow Node.js resolution
|
|
- **Build tools** — Tools that scan `node_modules` directly
|
|
|
|
If you encounter issues, you can:
|
|
|
|
1. **Switch to hoisted mode** for specific projects:
|
|
|
|
```bash terminal icon="terminal"
|
|
bun install --linker hoisted
|
|
```
|
|
|
|
2. **Report compatibility issues** to help improve isolated install support
|
|
|
|
### Performance considerations
|
|
|
|
- **Install time** — May be slightly slower due to symlink operations
|
|
- **Disk usage** — Similar to hoisted (uses symlinks, not file copies)
|
|
- **Memory usage** — Higher during install due to complex peer resolution
|
|
|
|
## Migration guide
|
|
|
|
### From npm/Yarn
|
|
|
|
```bash terminal icon="terminal"
|
|
# Remove existing node_modules and lockfiles
|
|
rm -rf node_modules package-lock.json yarn.lock
|
|
|
|
# Install with isolated linker
|
|
bun install --linker isolated
|
|
```
|
|
|
|
### From pnpm
|
|
|
|
Isolated installs are conceptually similar to pnpm, so migration should be straightforward:
|
|
|
|
```bash terminal icon="terminal"
|
|
# Remove pnpm files
|
|
$ rm -rf node_modules pnpm-lock.yaml
|
|
|
|
# Install with Bun's isolated linker
|
|
bun install --linker isolated
|
|
```
|
|
|
|
The main difference is that Bun uses symlinks in `node_modules` while pnpm uses a global store with symlinks.
|
|
|
|
## When to use isolated installs
|
|
|
|
**Use isolated installs when:**
|
|
|
|
- Working in monorepos with multiple packages
|
|
- Strict dependency management is required
|
|
- Preventing phantom dependencies is important
|
|
- Building libraries that need deterministic dependencies
|
|
|
|
**Use hoisted installs when:**
|
|
|
|
- Working with legacy code that assumes flat `node_modules`
|
|
- Compatibility with existing build tools is required
|
|
- Working in environments where symlinks aren't well supported
|
|
- You prefer the simpler traditional npm behavior
|
|
|
|
## Related documentation
|
|
|
|
- [Package manager > Workspaces](/pm/workspaces) — Monorepo workspace management
|
|
- [Package manager > Lockfile](/pm/lockfile) — Understanding Bun's lockfile format
|
|
- [CLI > install](/pm/cli/install) — Complete `bun install` command reference
|