mirror of
https://github.com/affaan-m/ECC.git
synced 2026-10-19 06:23:46 +02:00
docs(skills): refresh bun-runtime guidance for Bun 1.4
This commit is contained in:
Chisa Kotegawa
@@ -16,21 +16,28 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
|
||||
- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with Jest-like API.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reports known vulnerabilities. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
## Examples
|
||||
|
||||
### Run and install
|
||||
|
||||
```bash
|
||||
# Install dependencies (creates/updates bun.lock or bun.lockb)
|
||||
# Install dependencies (creates/updates bun.lock)
|
||||
bun install
|
||||
|
||||
# Run a script or file
|
||||
@@ -53,6 +60,8 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` with `--update-timings` (merge per-file duration data across shards so `--shard`/`--parallel` can front-load the slowest files). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
import { expect, test } from "bun:test";
|
||||
@@ -78,6 +87,6 @@ Bun.serve({
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.
|
||||
- Commit the lockfile (`bun.lock`) for reproducible installs.
|
||||
- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.
|
||||
- Keep dependencies up to date; Bun and the ecosystem evolve quickly.
|
||||
|
||||
@@ -17,21 +17,28 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
|
||||
- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with Jest-like API.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reports known vulnerabilities. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
## Examples
|
||||
|
||||
### Run and install
|
||||
|
||||
```bash
|
||||
# Install dependencies (creates/updates bun.lock or bun.lockb)
|
||||
# Install dependencies (creates/updates bun.lock)
|
||||
bun install
|
||||
|
||||
# Run a script or file
|
||||
@@ -54,6 +61,8 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` with `--update-timings` (merge per-file duration data across shards so `--shard`/`--parallel` can front-load the slowest files). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
import { expect, test } from "bun:test";
|
||||
@@ -79,6 +88,6 @@ Bun.serve({
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.
|
||||
- Commit the lockfile (`bun.lock`) for reproducible installs.
|
||||
- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.
|
||||
- Keep dependencies up to date; Bun and the ecosystem evolve quickly.
|
||||
|
||||
@@ -17,21 +17,28 @@ Bunは高速なオールインワンJavaScriptランタイムとツールキッ
|
||||
|
||||
## 動作方法
|
||||
|
||||
- **ランタイム**：ドロップイン互換のNodeランタイム（JavaScriptCoreで構築、Zigで実装）。
|
||||
- **パッケージマネージャー**：`bun install`はnpm/yarnよりも大幅に高速です。ロックファイルは`bun.lock`（テキスト）（デフォルト）。古いバージョンは`bun.lockb`（バイナリ）を使用しました。
|
||||
- **バージョンの基準**：以下のガイダンスはBun 1.4.xを対象としています。CLIフラグはメジャーバージョン間で変更されているため、フラグ名に依存する前に`bun --version`で実際のバージョンを確認してください。
|
||||
- **ランタイム**：ドロップイン互換のNodeランタイム（JavaScriptCore上に構築）。Bun 1.4以降、ランタイム自体はRustで実装されています（Zigから移行）。100%Node互換ではありません — 一部のネイティブアドオン、あまり一般的でない`node:`内部APIや、Node固有の内部動作に依存するパッケージは動作しないことがあります。本番環境で依存する前に検証してください。
|
||||
- **パッケージマネージャー**：`bun install`は一般にnpm/yarnより高速です。実際の速度差はプロジェクトサイズ、ネットワーク状況、キャッシュの状態によって変わります。ロックファイルは現行のBunでは`bun.lock`（テキスト）がデフォルトです。古いバージョンは`bun.lockb`（バイナリ）を使用しており、Bunは移行のため現在もこれを読み込めますが、新規プロジェクトは`bun.lock`を使うべきです。
|
||||
- **バンドラー**：アプリとライブラリ用の組み込みバンドラーとトランスパイラー。
|
||||
- **テストランナー**：Jest様のAPIを備えた組み込み`bun test`。
|
||||
|
||||
**Nodeからの移行**：`node script.js`を`bun run script.js`または`bun script.js`に置き換えます。`npm install`の代わりに`bun install`を実行します。ほとんどのパッケージは機能します。npm スクリプトには`bun run`を使用します。`bun x`をnpxスタイルの1回限りの実行に使用します。Nodeの組み込みはサポートされています。パフォーマンスの向上のため、Bunチャネルが存在する場合は優先。
|
||||
**Nodeからの移行**：`node script.js`を`bun run script.js`または`bun script.js`に置き換えます。`npm install`の代わりに`bun install`を実行します。ほとんどのパッケージは機能します。npm スクリプトには`bun run`を使用します。`bun x`をnpxスタイルの1回限りの実行に使用します。Nodeの組み込みはサポートされています。パフォーマンスの向上のため、Bun APIが存在する場合は優先してください。
|
||||
|
||||
**パッケージ・ワークスペースコマンド**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]`で依存関係を管理し、`bun outdated`で古い依存関係を一覧表示します。`bun pm ls`はロックファイルから導出した依存関係ツリーを表示するもので、実際にディスクにインストールされている内容の証明ではありません。読み取り専用の`bun audit`は既知の脆弱性を報告し、変更を伴う`bun audit fix`はその修正を適用し、`bun dedupe`は重複インストールを解消し、`bun prune`は参照されなくなったパッケージを削除します。モノレポはルートの`package.json`の`workspaces`配列を使用します（npm/yarnと同じ規約）。特定のワークスペースでスクリプトを実行するには`bun run --filter <pkg-name> <script>`を使用します。
|
||||
|
||||
**組み込みAPI**：依存関係を追加する前にこれらを検討してください — ファイルI/Oには`Bun.file` / `Bun.write`、組み込みSQLiteデータベースには`bun:sqlite`、HTTP/WebSocketサーバーには`Bun.serve`、SQLデータベースには[`Bun.sql`](https://bun.com/docs/runtime/sql)、Redisには[`Bun.redis`](https://bun.com/docs/runtime/redis)、S3互換オブジェクトストレージには[`Bun.S3Client`](https://bun.com/docs/runtime/s3)。その他の新機能は[1.4リリースノート](https://bun.com/blog/bun-v1.4)を参照してください。
|
||||
|
||||
**Vercel**：プロジェクト設定でBunに設定をランタイムに設定します。ビルド：`bun run build`または`bun build ./src/index.ts --outdir=dist`。インストール：再現可能なデプロイの場合は`bun install --frozen-lockfile`。
|
||||
|
||||
**参考**：[Bun 1.4 リリースノート](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
## 例
|
||||
|
||||
### 実行とインストール
|
||||
|
||||
```bash
|
||||
# 依存関係をインストール（bun.lockまたはbun.lockbを作成/更新）
|
||||
# 依存関係をインストール（bun.lockを作成/更新）
|
||||
bun install
|
||||
|
||||
# スクリプトまたはファイルを実行
|
||||
@@ -54,6 +61,8 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
CI向けに、Bun 1.4のテストランナーは以下を追加します：`bun test --changed[=<ref>]`（gitのコミット/ブランチと比較して変更の影響を受けるテストファイルを実行 — 編集されたテストファイルだけでなく、変更されたソースを利用するテストも含む）、`bun test --isolate`（テストファイルごとに新しいグローバルオブジェクトで実行し、あるファイルのリークが他に影響しないようにする。`--parallel`使用時は暗黙的に有効）、`bun test --parallel[=<n>]`（N個のワーカープロセスでテストファイルを実行、デフォルトはCPUコア数）、`bun test --shard=<n>/<count>`（1つのスイートをCIランナー間で分割）、`bun test --timings=<file>`と`--update-timings`（複数シャードの所要時間データをマージし、`--shard`/`--parallel`が最も遅いファイルから実行できるようにする）。例：`bun test --parallel --timings=./test-timings.json --update-timings`。インストールされているバージョンの正確なフラグの挙動は`bun test --help`で確認してください。
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
import { expect, test } from "bun:test";
|
||||
@@ -63,8 +72,22 @@ test("add", () => {
|
||||
});
|
||||
```
|
||||
|
||||
## 常見の問題
|
||||
### ランタイムAPI
|
||||
|
||||
- `bun install`は`node_modules`を作成しますが、シンボリックリンクの多用により構造が異なります。
|
||||
- 古い依存関係にはBun互換性の問題がある可能性があります。Node にフォールバックする。
|
||||
- VercelでBun使用時は設定とビルドコマンドが必須。
|
||||
```typescript
|
||||
const file = Bun.file("package.json");
|
||||
const json = await file.json();
|
||||
|
||||
Bun.serve({
|
||||
port: 3000,
|
||||
fetch(req) {
|
||||
return new Response("Hello");
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## ベストプラクティス
|
||||
|
||||
- 再現可能なインストールのため、ロックファイル（`bun.lock`）をコミットする。
|
||||
- スクリプトには`bun run`を優先する。TypeScriptの場合、Bunは`.ts`をネイティブに実行する。
|
||||
- 依存関係を最新に保つ。Bunとそのエコシステムは急速に進化している。
|
||||
|
||||
@@ -17,21 +17,28 @@ Bun 是一个快速的全能 JavaScript 运行时和工具集：运行时、包
|
||||
|
||||
## 工作原理
|
||||
|
||||
* **运行时**：开箱即用的 Node 兼容运行时（基于 JavaScriptCore，用 Zig 实现）。
|
||||
* **包管理器**：`bun install` 比 npm/yarn 快得多。在当前 Bun 中，锁文件默认为 `bun.lock`（文本）；旧版本使用 `bun.lockb`（二进制）。
|
||||
* **版本基线**：以下内容以 Bun 1.4.x 为准。CLI 参数在不同大版本之间有变化，依赖具体参数名之前请先用 `bun --version` 核实实际版本。
|
||||
* **运行时**：开箱即用的 Node 兼容运行时（基于 JavaScriptCore）。自 Bun 1.4 起，运行时本身改用 Rust 实现（此前为 Zig）。并非 100% 兼容 Node——部分原生插件、较少使用的 `node:` 内部 API，以及依赖 Node 特定内部行为的包仍可能失败；生产环境依赖前请自行验证。
|
||||
* **包管理器**：`bun install` 通常比 npm/yarn 更快；实际差距取决于项目规模、网络状况和缓存状态。在当前 Bun 中，锁文件默认为 `bun.lock`（文本）；旧版本使用 `bun.lockb`（二进制），Bun 目前仍可读取该格式以便迁移，但新项目应使用 `bun.lock`。
|
||||
* **打包器**：用于应用程序和库的内置打包器和转译器。
|
||||
* **测试运行器**：内置的 `bun test`，具有类似 Jest 的 API。
|
||||
|
||||
**从 Node 迁移**：将 `node script.js` 替换为 `bun run script.js` 或 `bun script.js`。运行 `bun install` 代替 `npm install`；大多数包都能工作。使用 `bun run` 来执行 npm 脚本；使用 `bun x` 进行 npx 风格的临时运行。支持 Node 内置模块；在存在 Bun API 的地方优先使用它们以获得更好的性能。
|
||||
|
||||
**包与工作区命令**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` 管理依赖；`bun outdated` 列出过时的依赖；`bun pm ls` 显示的是根据锁文件推导出的依赖树，并非磁盘上实际安装内容的证明。只读检查用 `bun audit` 报告已知漏洞；会修改内容的命令有 `bun audit fix`（应用修复）、`bun dedupe`（消除重复安装）和 `bun prune`（移除不再被引用的包）。多包仓库（monorepo）通过根 `package.json` 中的 `workspaces` 数组配置（与 npm/yarn 相同的约定）；使用 `bun run --filter <pkg-name> <script>` 在指定工作区运行脚本。
|
||||
|
||||
**内置 API**：在添加依赖之前，优先考虑这些内置能力——文件 I/O 使用 `Bun.file` / `Bun.write`；内置 SQLite 数据库使用 `bun:sqlite`；HTTP/WebSocket 服务器使用 `Bun.serve`；SQL 数据库使用 [`Bun.sql`](https://bun.com/docs/runtime/sql)；Redis 使用 [`Bun.redis`](https://bun.com/docs/runtime/redis)；S3 兼容对象存储使用 [`Bun.S3Client`](https://bun.com/docs/runtime/s3)。其余新特性参见 [1.4 发布说明](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
**Vercel**：在项目设置中将运行时设置为 Bun。构建命令：`bun run build` 或 `bun build ./src/index.ts --outdir=dist`。安装命令：`bun install --frozen-lockfile` 用于可重复的部署。
|
||||
|
||||
**参考**：[Bun 1.4 发布说明](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
## 示例
|
||||
|
||||
### 运行和安装
|
||||
|
||||
```bash
|
||||
# Install dependencies (creates/updates bun.lock or bun.lockb)
|
||||
# Install dependencies (creates/updates bun.lock)
|
||||
bun install
|
||||
|
||||
# Run a script or file
|
||||
@@ -54,6 +61,8 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
面向 CI，Bun 1.4 的测试运行器新增了：`bun test --changed[=<ref>]`（运行相对某个 git 提交/分支受影响的测试文件——不仅是被修改的测试文件本身，还包括依赖了被修改源文件的测试）、`bun test --isolate`（每个测试文件使用全新的全局对象运行，避免一个文件的句柄泄漏影响另一个文件；使用 `--parallel` 时默认启用）、`bun test --parallel[=<n>]`（用 N 个工作进程并行运行测试文件，默认等于 CPU 核心数）、`bun test --shard=<n>/<count>`（将一个测试套件拆分到多个 CI 运行器上）、以及 `bun test --timings=<file>` 配合 `--update-timings`（合并多个分片的单文件耗时数据，使 `--shard`/`--parallel` 能优先调度最慢的文件）。示例：`bun test --parallel --timings=./test-timings.json --update-timings`。具体参数行为请以本地 `bun test --help` 输出为准。
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
import { expect, test } from "bun:test";
|
||||
@@ -79,6 +88,6 @@ Bun.serve({
|
||||
|
||||
## 最佳实践
|
||||
|
||||
* 提交锁文件（`bun.lock` 或 `bun.lockb`）以实现可重复的安装。
|
||||
* 提交锁文件（`bun.lock`）以实现可重复的安装。
|
||||
* 在脚本中优先使用 `bun run`。对于 TypeScript，Bun 原生运行 `.ts`。
|
||||
* 保持依赖项最新；Bun 和生态系统发展迅速。
|
||||
|
||||
@@ -18,21 +18,28 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
|
||||
- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with Jest-like API.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reports known vulnerabilities. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
## Examples
|
||||
|
||||
### Run and install
|
||||
|
||||
```bash
|
||||
# Install dependencies (creates/updates bun.lock or bun.lockb)
|
||||
# Install dependencies (creates/updates bun.lock)
|
||||
bun install
|
||||
|
||||
# Run a script or file
|
||||
@@ -55,6 +62,8 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` with `--update-timings` (merge per-file duration data across shards so `--shard`/`--parallel` can front-load the slowest files). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
import { expect, test } from "bun:test";
|
||||
@@ -80,6 +89,6 @@ Bun.serve({
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.
|
||||
- Commit the lockfile (`bun.lock`) for reproducible installs.
|
||||
- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.
|
||||
- Keep dependencies up to date; Bun and the ecosystem evolve quickly.
|
||||
|
||||
Reference in New Issue
Block a user