File I/O

Read and write files using Bun’s optimized file I/O APIs, including BunFile, FileSink, and directory operations via node:fs.

Bun.file and Bun.write are heavily optimized and are the recommended way to perform file-system tasks in Bun. For operations not yet available natively—such as mkdir or readdir—use Bun’s nearly complete implementation of node:fs.

Reading files with Bun.file()

Bun.file(path) returns a BunFile instance — a lazily-loaded reference to a file on disk. The file is not read until you call a method on it.

const file = Bun.file("data.txt"); // relative to cwd
file.size;  // number of bytes
file.type;  // MIME type, e.g. "text/plain;charset=utf-8"

BunFile conforms to the Blob interface. Read its contents in multiple formats:

Read as text

const text = await Bun.file("data.txt").text();

File references

You can create a BunFile using a path string, a file descriptor number, or a file:// URL:

Bun.file("foo.txt");                    // relative to cwd
Bun.file("/absolute/path/to/foo.txt");  // absolute path
Bun.file(1234);                         // file descriptor number
Bun.file(new URL(import.meta.url));     // reference to the current file

File metadata

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

file.size;          // number of bytes (0 if file doesn't exist)
file.type;          // MIME type string
await file.exists(); // boolean — false if file doesn't exist

A BunFile can reference a path that doesn’t exist yet. No error is thrown until you try to read it:

const ghost = Bun.file("missing.txt");
ghost.size;             // 0
ghost.type;             // "text/plain;charset=utf-8"
await ghost.exists();   // false

To override the inferred MIME type, pass a second argument:

const file = Bun.file("data.json", { type: "application/json" });
file.type; // "application/json;charset=utf-8"

Standard I/O streams

Bun exposes stdin, stdout, and stderr as BunFile instances:

Bun.stdin;   // readonly
Bun.stdout;
Bun.stderr;

Deleting files

await Bun.file("logs.json").delete();

---

Writing files with Bun.write()

Bun.write(destination, data) writes data to disk and returns a Promise<number> (bytes written).

Destination can be a string path, file:// URL, or BunFile. Data can be a string, Blob, BunFile, ArrayBuffer, TypedArray, or Response.

Write a string

await Bun.write("output.txt", "Hello, world!");

Bun automatically selects the fastest available system call for each input/output combination (e.g., copy_file_range on Linux, clonefile on macOS).

---

Incremental writing with FileSink

For streaming or incremental writes, use FileSink — Bun’s native incremental file writer.

Basic usage

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

writer.write("first chunk\n");
writer.write("second chunk\n");

writer.flush(); // flush buffer to disk
writer.end();   // flush and close

High water mark

Control when the buffer auto-flushes by setting a highWaterMark:

const writer = Bun.file("output.txt").writer({
  highWaterMark: 1024 * 1024, // flush after 1 MB
});

Process lifetime

By default, the Bun process stays alive until FileSink is closed. Opt out with .unref():

writer.unref(); // process won't wait for this sink
writer.ref();   // re-attach if needed

---

Module path helpers

Bun provides module-relative path helpers on import.meta:

import.meta.dir;   // absolute path to the directory of the current file
import.meta.file;  // filename of the current file (e.g. "index.ts")
import.meta.path;  // absolute path to the current file

These are useful for constructing paths relative to the current source file:

const configPath = import.meta.dir + "/config.json";
const config = await Bun.file(configPath).json();

---

Directory operations

Bun does not yet have a native directory API. Use node:fs instead.

Read a directory

import { readdir } from "node:fs/promises";

const files = await readdir(import.meta.dir);

---

API reference

interface Bun {
  stdin: BunFile;
  stdout: BunFile;
  stderr: BunFile;

  file(path: string | number | URL, options?: { type?: string }): BunFile;

  write(
    destination: string | number | BunFile | URL,
    input:
      | string
      | Blob
      | ArrayBuffer
      | SharedArrayBuffer
      | TypedArray
      | Response,
  ): Promise<number>;
}

interface BunFile extends Blob {
  readonly size: number;
  readonly type: string;

  text(): Promise<string>;
  json(): Promise<any>;
  bytes(): Promise<Uint8Array>;
  arrayBuffer(): Promise<ArrayBuffer>;
  stream(): ReadableStream;
  exists(): Promise<boolean>;
  delete(): Promise<void>;
  writer(params?: { highWaterMark?: number }): FileSink;
}

interface FileSink {
  write(
    chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
  ): number;
  flush(): number | Promise<number>;
  end(error?: Error): number | Promise<number>;
  ref(): void;
  unref(): void;
}

Glob

Bun.Glob provides fast native file globbing. Use it to scan directories or match strings against patterns.

import { Glob } from "bun";

// Scan a directory for all TypeScript files
const glob = new Glob("**/*.ts");

for await (const file of glob.scan(".")) {
  console.log(file); // "src/index.ts", "src/utils/helpers.ts", ...
}

Match a string against a pattern:

const glob = new Glob("*.{ts,tsx}");

glob.match("index.ts");   // true
glob.match("index.js");   // false
glob.match("App.tsx");    // true

Scan options:

for await (const file of glob.scan({
  cwd: "./src",        // root directory (default: process.cwd())
  dot: true,           // include dotfiles
  absolute: true,      // return absolute paths
  onlyFiles: true,     // exclude directories (default: true)
})) {
  console.log(file);
}

Synchronous scan:

const files = [...glob.scanSync("./src")];

Supported glob syntax: *, **, ?, [abc], {a,b}, and negation with !.