bun-file-io_skill

Overview

This skill documents preferred file I/O patterns and APIs for working with Bun in the codebase. It highlights Bun-specific reading, writing, scanning, and deletion methods, and notes when to fall back to Node's fs/promises for directory tasks. The goal is consistent, efficient, and safe file operations across the project.

How this skill works

It describes Bun.file as a lazy file handle that exposes helpers like text(), json(), arrayBuffer(), bytes(), stream(), and exists() for reading. Writing is handled via Bun.write or file.writer() for incremental writes, while Bun.Glob combined with Array.fromAsync(glob.scan(...)) is recommended for scanning. For external tools, Bun.which locates binaries and Bun.spawn runs them; decode streams with Bun.readableStreamToText/Bytes/JSON.

When to use it

• When reading or writing regular files—prefer Bun.file(...) and its read helpers.
• When scanning directories or patterns—use Bun.Glob + Array.fromAsync(glob.scan(...)).
• When running external tools—use Bun.which to locate binaries and Bun.spawn to execute.
• When working with directory creation, recursive reads, or readdir—use node:fs/promises.
• When deleting files—use Bun.file(path).delete() for single-file deletes.

Best practices

• Prefer Bun APIs over node:fs for file access; reserve node:fs/promises for directory-level operations (mkdir, readdir, recursive).
• Always check Bun.file(path).exists() before attempting to read to avoid exceptions.
• For large or binary files, use arrayBuffer() and check file.type for MIME handling.
• Use path.join/path.resolve to build paths to avoid cross-platform issues.
• Favor promise .catch(...) handling for simple flows; use try/catch only when needed for control flow or sync-like logic.

Example use cases

• Reading a UTF-8 source file: const text = await Bun.file(path).text() after exists() check.
• Writing large output: await Bun.write(Bun.file(destPath), largeStringOrBuffer).
• Scanning project files: const entries = await Array.fromAsync(glob.scan({ cwd, absolute: true, onlyFiles: true, dot: true })).
• Running a formatter: const bin = Bun.which('prettier'); const proc = Bun.spawn({ cmd: [bin, '--check', file] }); const stderr = await Bun.readableStreamToText(proc.stderr).
• Deleting artifact files: await Bun.file(tempPath).delete().