File I/O

Read and write files with Bun’s fast file system APIs

Bun provides fast, built-in APIs for file operations including reading, writing, and streaming files.

Bun.file()

Create a BunFile object representing a file:

const file = Bun.file("./package.json");

// Read as text
const text = await file.text();

// Read as JSON
const json = await file.json();

// Read as ArrayBuffer
const buffer = await file.arrayBuffer();

// Read as stream
const stream = file.stream();

File Properties

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

file.size; // number (bytes)
file.type; // string (MIME type)
file.name; // string (file path)
file.lastModified; // number (timestamp)

From File Descriptor

import { openSync } from "node:fs";

const fd = openSync("./file.txt", "r");
const file = Bun.file(fd);

From Blob

const blob = new Blob(["Hello"]);
const file = Bun.file(blob);

Bun.write()

Write data to a file:

// Write string
await Bun.write("./output.txt", "Hello World");

// Write Buffer/ArrayBuffer
await Bun.write("./data.bin", new Uint8Array([1, 2, 3]));

// Write from Response
const response = await fetch("https://bun.sh");
await Bun.write("./bun.html", response);

// Write from file to file
await Bun.write("./copy.txt", Bun.file("./source.txt"));

Write Options

await Bun.write("./secret.txt", data, {
  mode: 0o600, // File permissions (octal)
  createPath: true, // Create parent directories
});

Write to BunFile

const file = Bun.file("./output.txt");
await Bun.write(file, "Hello");

// Or use file.writer()
const writer = file.writer();
writer.write("Hello ");
writer.write("World");
await writer.end();

Reading Files

Synchronous Reading

import { readFileSync } from "node:fs";

const content = readFileSync("./file.txt", "utf-8");

Asynchronous Reading

const file = Bun.file("./data.json");

// As text
const text = await file.text();

// As JSON
const data = await file.json();

// As ArrayBuffer
const buffer = await file.arrayBuffer();

// As Uint8Array  
const bytes = new Uint8Array(await file.arrayBuffer());

Reading with Offset

const file = Bun.file("./large.dat");

// Read first 1024 bytes
const header = file.slice(0, 1024);
const data = await header.arrayBuffer();

// Read from offset
const chunk = file.slice(1024, 2048);

Streaming Files

Stream Reading

const file = Bun.file("./large.txt");
const stream = file.stream();

for await (const chunk of stream) {
  console.log("Chunk:", chunk);
}

Stream Writing

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

writer.write("Line 1\n");
writer.write("Line 2\n");
writer.write("Line 3\n");

await writer.end();

Piping Streams

const input = Bun.file("./input.txt");
const output = Bun.file("./output.txt");

await input.stream().pipeTo(output.writer());

File Existence

const file = Bun.file("./maybe.txt");

if (await file.exists()) {
  console.log("File exists");
}

File Stats

Use Node.js fs module for file stats:

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

const stats = await stat("./file.txt");

stats.size; // bytes
stats.mtime; // modification time
stats.isFile(); // true
stats.isDirectory(); // false

Stdin/Stdout/Stderr

Reading Stdin

const stdin = Bun.stdin.stream();

for await (const chunk of stdin) {
  console.log("Received:", new TextDecoder().decode(chunk));
}

Writing to Stdout

const stdout = Bun.stdout.writer();

stdout.write("Hello");
stdout.write(" World\n");
await stdout.flush();

Writing to Stderr

const stderr = Bun.stderr.writer();
stderr.write("Error message\n");
await stderr.flush();

File Watching

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

const watcher = watch("./src", { recursive: true });

for await (const event of watcher) {
  console.log(event.eventType, event.filename);
}

Directory Operations

Read Directory

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

const files = await readdir("./src");
for (const file of files) {
  console.log(file);
}

Create Directory

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

await mkdir("./new-dir", { recursive: true });

Remove Directory

import { rmdir, rm } from "node:fs/promises";

// Remove empty directory
await rmdir("./empty-dir");

// Remove directory recursively
await rm("./dir", { recursive: true, force: true });

File Utilities

Copy File

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

await copyFile("./source.txt", "./dest.txt");

Rename/Move File

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

await rename("./old.txt", "./new.txt");

Delete File

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

await unlink("./file.txt");

Check Access

import { access, constants } from "node:fs/promises";

try {
  await access("./file.txt", constants.R_OK | constants.W_OK);
  console.log("Can read and write");
} catch {
  console.log("Cannot access");
}

Temporary Files

import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";

const tempDir = await mkdtemp(join(tmpdir(), "bun-"));

try {
  // Use temp directory
  await Bun.write(join(tempDir, "temp.txt"), "data");
} finally {
  // Cleanup
  await rm(tempDir, { recursive: true, force: true });
}

Type Signatures

interface BunFile extends Blob {
  readonly size: number;
  readonly type: string;
  readonly name?: string;
  readonly lastModified: number;
  
  text(): Promise<string>;
  json<T = any>(): Promise<T>;
  arrayBuffer(): Promise<ArrayBuffer>;
  stream(): ReadableStream<Uint8Array>;
  
  slice(begin?: number, end?: number): BunFile;
  exists(): Promise<boolean>;
  
  writer(options?: { highWaterMark?: number }): FileSink;
}

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

function file(path: string): BunFile;
function file(fd: number): BunFile;
function file(blob: Blob): BunFile;

function write(
  destination: string | BunFile,
  data: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer | Blob | Response,
  options?: { mode?: number; createPath?: boolean }
): Promise<number>;