blog.dopana

Quay lại

Bạn có một codebase Node.js. Nó chạy ngon. Team muốn thử Bun vì khởi động nhanh hơn, test runner có sẵn trong runtime, và cài dependency chỉ mất vài giây thay vì vài phút.

Rồi bạn mở file đầu tiên và thấy mấy dòng này ở khắp nơi:

src/config.ts
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const configPath = path.join(__dirname, "config.json");
const raw = fs.readFileSync(configPath, "utf8");
ts

Câu hỏi lóe lên ngay lập tức: “Có phải tôi phải viết lại tất cả không?”

Câu trả lời ngắn là không — và đây là điều quan trọng nhất cần hiểu về thiết kế của Bun. Bun không phải một hành tinh khác. Nó là hành tinh cũ với một chiếc thùng đồ nghề lớn hơn.

Câu trả lời trong 10 giây#

Node.jsBun thay thếCó nên viết lại không?
node:fsBun.file(), Bun.write(), Bun.$Chỉ khi đọc/ghi nội dung file đơn giản
node:pathpath / node:pathKhông — giữ nguyên là được
node:urlURL, URLSearchParams (Web API)Chỉ khi bạn thực sự muốn dùng Web API
node:child_processBun.$, Bun.spawnTùy chọn, khá đẹp cho lệnh shell

Mô hình tư duy: thùng đồ nghề lớn hơn, chứ không phải thùng đồ nghề khác#

Hãy dùng hình ảnh này để toàn bộ chủ đề trở nên dễ hiểu.

Hãy tưởng tượng bạn đứng trong xưởng mộc. Node.js trao cho bạn một chiếc thắt lưng đồ nghề gồm búa, cưa và tua nha. Rồi Bun xuất hiện và nói: “Đây là chiếc búa tốt hơn, cưa điện và máy đo laser — à, và chiếc búa cũ vẫn dùng được bình thường.”

Có công cụ mới không có nghĩa bạn phải thay cái cũ. Nó có nghĩa là bạn giờ có lựa chọn, và nên dùng công cụ mới khi nó thực sự làm code của bạn dễ đọc hơn.

Lớp tương thích của Bun được thiết kế rất sâu. node:fs, node:path, node:url, node:http cùng hàng trăm module khác chạy trên Bun với đúng ngữ nghĩa như Node. Đó chính là điểm mấu chốt: phần lớn code Node hiện có chạy không cần sửa một dòng nào.

[!TIP] Hãy xem API native của Bun là lối nâng cấp, không phải yêu cầu migrate. Bạn có thể áp dụng từng file một, vào đúng lúc code trở nên dễ đọc hơn.

1. node:fs → Bun.file() và Bun.write()#

Trao đổi cơ bản#

Node.js
// Node
import fs from "node:fs";

const text = fs.readFileSync("file.txt", "utf8");
fs.writeFileSync("file.txt", "hello");
ts
Bun
// Bun
const text = await Bun.file("file.txt").text();
await Bun.write("file.txt", "hello");
ts

Đó là toàn bộ ý tưởng: Bun.file(path) trả về một file handle (thực chất là BunFile, tuân thủ chuẩn Blob của Web), còn Bun.write(destination, data) ghi mọi thứ xuống đĩa.

Kiểm tra file có tồn tại không#

const exists = await Bun.file("file.txt").exists();
ts

Dễ chịu hơn nhiều so với mẹo quen thuộc trong Node: try { fs.accessSync(p) } catch { false }.

[!WARNING] Bun.file() là thao tác lazy — tạo handle không hề chạm vào đĩa và không bao giờ throw, kể cả khi file không tồn tại. Một file không tồn tại sẽ báo size === 0 và type === "text/plain;charset=utf-8". Lỗi chỉ xuất hiện khi bạn thực sự đọc nó (ENOENT: no such file or directory). Vì vậy, hãy dùng .exists() khi cần kiểm tra sự tồn tại, đừng coi Bun.file() là một bước kiểm tra.

Đọc JSON#

const data = await Bun.file("config.json").json();
ts

Không còn JSON.parse(fs.readFileSync(...)) nữa. .json() parse sẵn cho bạn.

Mọi thứ một BunFile làm được#

const file = Bun.file("data.bin");

await file.text();         // string
await file.json();         // JSON đã parse
await file.arrayBuffer();  // ArrayBuffer
await file.bytes();        // Uint8Array
file.stream();             // ReadableStream
await file.exists();       // boolean
await file.delete();       // xoá file
ts

Vì một BunFile chính là một Blob, nó có thể đưa thẳng vào fetch, Response, hoặc bất kỳ API nào nhận dữ liệu nhị phân.

Ghi file#

Bun.write() là một công cụ đa năng. Đích có thể là đường dẫn, URL file:// hoặc một BunFile; dữ liệu có thể là string, Blob, ArrayBuffer, typed array, hay thậm chí là body của một Response.

await Bun.write("output.txt", "plain text");
await Bun.write("output.txt", new Uint8Array([1, 2, 3]));

// Copy file — Bun tự chọn syscall nhanh nhất theo từng nền tảng
await Bun.write(Bun.file("copy.txt"), Bun.file("input.txt"));

// Tải thẳng về đĩa
const response = await fetch("https://bun.com");
await Bun.write("index.html", response);

// Đẩy nội dung file ra stdout
await Bun.write(Bun.stdout, Bun.file("input.txt"));
ts

Bun.write() resolve với số byte đã ghi, rất tiện để log:

const bytes = await Bun.write("output.txt", "hello");
console.log(`wrote ${bytes} bytes`); // wrote 5 bytes
ts

Ghi dần bằng FileSink#

Khi file quá lớn để nạp vào RAM, hãy dùng writer:

const writer = Bun.file("output.txt").writer();

writer.write("it was the best of times\n");
writer.write("it was the worst of times\n");

await writer.end(); // flush + đóng file
ts

[!NOTE] Một khác biệt hành vi đáng lưu tâm: Bun.write() tự tạo thư mục cha nếu chưa có, trong khi fs.writeFileSync() của Node sẽ ném ENOENT khi thư mục cha không tồn tại. Đã kiểm chứng trên Bun 1.4.3 — Bun.write("a/b/c.txt", "x") thành công và tự tạo cả a/b/.

node:fs vẫn nắm giữ những gì?#

Bun.file() giải quyết nội dung file. Nó không giải quyết hệ thống file. Với những thao tác dưới đây, hãy giữ node:fs — bản implementation của Bun rất nhanh:

src/scan.ts
import { mkdir, readdir, stat } from "node:fs/promises";

// Tạo cây thư mục
await mkdir("build/output", { recursive: true });

// Liệt kê file
const entries = await readdir(import.meta.dir, { recursive: true });

// Lấy metadata
const info = await stat("package.json");
console.log(info.size, info.mtime);
ts

Chính tài liệu của Bun nói thẳng: for operations they don’t cover, such as mkdir or readdir, use Bun’s nearly complete implementation of the node:fs module.

Và lối thoát hiểm cho shell: Bun.$#

Đọc ghi file không phải là toàn bộ I/O trong code của bạn. Thỉnh thoảng bạn cần chạy một lệnh:

Node.js
// Node
import { execSync } from "node:child_process";
execSync("git rev-parse HEAD");
ts
Bun
// Bun
import { $ } from "bun";

const hash = await $`git rev-parse HEAD`.text();
ts

Bun.$ là một shell giống bash, cross-platform, được viết bằng Rust. Nó không phải là wrapper quanh /bin/sh — đây là một bản cài lại, chạy ngay trong tiến trình Bun, nên hành vi giống nhau trên Windows, macOS và Linux.

await $`ls -la`.quiet();                       // không in ra gì
await $`echo "hi"`.text();                     // "hi\n"
await $`cat package.json`.json();              // JSON đã parse
for await (const line of $`cat list.txt`.lines()) { /* ... */ }
ts

Và một chi tiết bảo mật rất đáng lưu tâm: giá trị nội suy được escape mặc định, nên input từ người dùng không thể thoát ra ngoài lệnh.

const userInput = "my-file.txt; rm -rf /";
await $`ls ${userInput}`; // ls nhận MỘT tham số nguyên chữ, không phải hai lệnh
ts

Khi cần kiểm soát tiến trình đầy đủ (pipe stdin/stdout, biến môi trường, exit code), hãy dùng Bun.spawn:

const proc = Bun.spawn(["echo", "hello"], { stdout: "pipe" });
const output = await new Response(proc.stdout).text();
await proc.exited;
console.log(output, proc.exitCode);
ts

2. node:path → cứ giữ nguyên#

import path from "node:path";

const file = path.join("src", "index.ts");
const dir = path.dirname(file);
const ext = path.extname(file);
const abs = path.resolve(file);
ts

Không có lợi ích gì khi thay thế node:path trong Bun:

  • Nó chỉ là logic xử lý chuỗi — không I/O, không magic runtime.
  • Nó nhận biết nền tảng (dấu phân cách Windows, ổ đĩa, đường dẫn UNC).
  • Bun cài đặt đầy đủ và vượt qua chính bộ test của Node cho module này.
  • Thay bằng nối chuỗi thủ công là một cú hạ cấp, không phải nâng cấp.

Một tiện ích riêng của Bun là biết file này nằm ở đâu:

import.meta.dir;  // "/a/b"      — đường dẫn tuyệt đối của thư mục chứa file này
import.meta.path; // "/a/b/c.ts" — đường dẫn tuyệt đối của file này
ts

Hãy so sánh với process.cwd() — nơi lệnh được chạy, chứ không phải nơi code nằm. import.meta.dir là câu trả lời của Bun cho bài toán kinh điển “làm sao tìm file nằm cạnh module của mình?”.

[!NOTE] Node.js cũng đã bắt kịp: từ Node 20.11 / 21.2, import.meta.dirname và import.meta.filename trở thành chuẩn. Nên nếu muốn code chạy được trên cả hai runtime, import.meta.dirname là cách viết portable, còn import.meta.dir là bản riêng của Bun.

3. node:url → ưu tiên Web API chuẩn#

Lớp URL không phải phát minh của Bun — đó là chuẩn Web, có mặt trong trình duyệt, Node, Deno, Bun, worker, mọi nơi.

const url = new URL("https://example.com/foo?bar=baz");

console.log(url.pathname);              // "/foo"
console.log(url.searchParams.get("bar")); // "baz"
console.log(url.host);                  // "example.com"
ts

URLSearchParams là cách dựng query string gọn gàng:

const params = new URLSearchParams({ page: "2", q: "bun runtime" });
console.log(`https://api.example.com/search?${params}`);
ts

Với trường hợp rất phổ biến là “đổi URL của module thành đường dẫn trên đĩa”, Node cần một hàm phụ:

Node.js
import { fileURLToPath } from "node:url";

const filename = fileURLToPath(import.meta.url);
ts

Trong Bun, thường bạn không cần hàm phụ nào:

Bun
const filename = import.meta.path;
const dirname = import.meta.dir;
ts

fileURLToPath() vẫn chạy được trong Bun (qua node:url) và vẫn là công cụ đúng khi bạn cần chuyển một URL file:// bất kỳ, không chỉ import.meta.url:

const localPath = fileURLToPath(new URL("../config/app.json", import.meta.url));
ts

Có nên viết lại? Cây quyết định#

node:fsCóKhông: thư mục, quyền, symlinknode:pathnode:urlCóKhông: path của moduleBạn import một module node:trong dự án BunModule nào?Chỉ đọc/ghi nội dung file?Dùng Bun.file() và Bun.write()Giữ node:fsGiữ node:pathKhông có lợi ích gì khi viết lạiCần Web URL API?Dùng URL vàURLSearchParamsDùng import.meta.path vàimport.meta.dir

Lộ trình migrate không gây đau#

  1. Trước tiên, đừng làm gì cả. Đổi node thành bun trong Dockerfile/CI rồi chạy test suite. Hầu hết code pass nguyên vẹn.
  2. Thay cái rườm rà, đừng thay logic. Đổi fs.readFileSync + JSON.parse thành await Bun.file(p).json() — đây là cải thiện khả năng đọc, không phải viết lại.
  3. Dùng Bun.$ cho các lệnh shell đang là execSync — bạn được thêm escaping và hành vi cross-platform miễn phí.
  4. Để yên node:path và node:url trừ khi bạn thực sự muốn dùng Web URL API.
  5. Giữ node:fs cho phần thư mục và quyền — bản node:fs của Bun rất nhanh và sẽ không biến mất.

Những cái bẫy đáng nhớ#

  • Bun.file() không bao giờ throw với file thiếu. Nó là một promise, không phải một check. Hãy dùng .exists().
  • Bun.write() trả về số byte, và tự tạo thư mục cha nếu thiếu.
  • Bun.file() nhận path, file descriptor, hoặc URL file://: Bun.file(new URL(import.meta.url)).
  • import.meta.path / import.meta.dir chỉ có ở Bun; import.meta.url mới là bản portable.
  • Các API đồng bộ của node:fs vẫn chạy tốt trong Bun. Chúng nhanh. “Async everywhere” là lựa chọn phong cách, không phải yêu cầu.
  • Đừng dùng Bun.file() cho thư mục — nó dành cho nội dung file.

TL;DR#

Nếu mục tiêu của bạn là tương thích với Bun, đừng viết lại tất cả:

node:fs   → Bun.file / Bun.write khi bạn muốn API native của Bun
node:path → giữ node:path
node:url  → URL / URLSearchParams, hoặc giữ node:url khi cần
text

Bun được thiết kế để chạy phần lớn code Node.js hiện có mà không cần thay đổi. Hãy dùng API native của Bun ở nơi chúng làm code dễ hiểu hơn, còn lại thì để nguyên.

Tài liệu tham khảo#