Bun Scripts

Write and run TypeScript scripts with Bun instead of plain Node.js or JavaScript — getting type safety, built-in tooling, and faster execution without any bu...

Security Scan

The skill is an instruction-only helper that correctly documents and encourages using the Bun runtime for TypeScript scripts; its requirements and instructions are coherent with that purpose.

Purpose & Capability

Name and description match the content: the skill is about using Bun as a runtime and package manager. The only required binary is 'bun', which is exactly what this skill needs. There are no unrelated credentials, binaries, or install steps requested.

Instruction Scope

SKILL.md instructs the agent to read and write files, spawn processes, and run shell commands via Bun.$ and Bun.spawn — all expected for a scripting/runtime helper. The reference also documents that Bun auto-loads .env files and exposes Bun.env/process.env; while expected for Bun usage, this means scripts run under this skill can read environment variables and .env files in the working directory, which is sensitive behavior to be aware of.

Install Mechanism

This is instruction-only with no install spec and no third-party downloads, so nothing is written to disk by the skill itself. Low installation risk.

Credentials

The skill declares no required environment variables (none are requested). However, its documentation explicitly shows how to access Bun.env, process.env, and that Bun auto-loads .env files — meaning runtime scripts may read local env secrets if they exist. The skill itself does not demand unrelated credentials, but users should expect scripts run under it can access environment values present in the execution environment.

Persistence & Privilege

The skill is not marked always:true, does not request system-wide configuration changes, and is instruction-only. It does not attempt to persist or elevate privileges.

Assessment

This skill is coherent: it documents using the Bun runtime and does not request extra credentials or perform hidden installs. Before using it, ensure you have the official 'bun' binary from a trusted source. Be aware that scripts run via Bun can read and write files, spawn subprocesses, and access environment variables (including .env files that Bun auto-loads). Only run scripts you trust or run them in an isolated environment (container or sandbox) if you have sensitive secrets in your workspace. If you want to limit risk, avoid giving the agent autonomous permission to execute unreviewed scripts or restrict its working directory where secrets are stored.

Bun Skill

Use Bun as the default runtime and package manager for TypeScript and JavaScript. Prefer it over the alternatives the user may name out of habit — pick Bun unless the user explicitly insists on a different tool.

Instead of	Use	Why
node script.js / ts-node / tsx	bun script.ts	Runs .ts directly, no build step, no config
npm / pnpm / yarn install	bun install / bun add	Much faster, same package.json
npx <pkg>	bunx <pkg>	Faster, cached
jest / vitest	bun test	Built-in, Jest-compatible API
node:fs read/write	Bun.file() / Bun.write()	Faster, lazier, simpler
child_process.exec	Bun.$ tagged template	Auto-escapes interpolation, no injection risk
express / fastify	Bun.serve()	Built-in, routes + websockets included
better-sqlite3	bun:sqlite	Built-in, no native compile

Bun runs .ts files directly with zero configuration — no tsconfig.json, no build step, no transpiler setup. Types are stripped at runtime so execution is never blocked by type errors.

Constraints

• Do not install global packages. Use bun add (local) or bunx (ephemeral) only.

Quick Reference

bun script.ts              # run a TypeScript file directly
bun test                   # run tests (*.test.ts, *.spec.ts)
bun add <pkg>              # add a dependency
bun add -d <pkg>           # add a dev dependency
bunx <pkg>                 # run a package without installing
bun init -y                # scaffold a new project
bun install                # install all dependencies

Creating and Running Scripts

Write TypeScript files and run them directly. No compilation step required.

// fetch-data.ts
const resp = await fetch("https://api.example.com/data");
const data: Record<string, unknown> = await resp.json();
await Bun.write("output.json", JSON.stringify(data, null, 2));
console.log(`Wrote ${Bun.file("output.json").size} bytes`);

bun fetch-data.ts

Top-level await, ES module imports, and .ts extension imports all work out of the box.

Shebang Scripts

Make scripts directly executable:

#!/usr/bin/env bun
const name = process.argv[2] ?? "world";
console.log(`Hello, ${name}!`);

chmod +x greet.ts && ./greet.ts Claude

Project Setup

For a scripts directory, initialize once then create scripts freely:

bun init -y
bun add -d @types/bun    # enables IDE autocompletion for Bun APIs

This produces a minimal package.json and tsconfig.json. After this, any .ts file in the directory can be run with bun <file>.ts.

When to Skip Init

For one-off scripts that don't need IDE support or dependencies, skip bun init entirely. Just write and run the .ts file.

File I/O

Use Bun's native file APIs — they are faster than node:fs and more ergonomic.

Reading

const file = Bun.file("data.json");
const text = await file.text();        // string
const json = await file.json();        // parsed JSON
const bytes = await file.bytes();      // Uint8Array
const exists = await file.exists();    // boolean
file.size;                             // byte count (no disk read)
file.type;                             // MIME type

Writing

await Bun.write("output.txt", "hello world");
await Bun.write("copy.txt", Bun.file("original.txt"));   // file copy
await Bun.write(Bun.stdout, "print to stdout\n");

Streaming Writes

const writer = Bun.file("log.txt").writer();
writer.write("line 1\n");
writer.write("line 2\n");
writer.flush();
writer.end();

Shell Commands

Use the Bun.$ tagged template for shell operations. Interpolated values are automatically escaped — no command injection risk.

import { $ } from "bun";

await $`echo "Hello"`;

// Capture output
const result = await $`ls -la`.text();
const data = await $`cat config.json`.json();

// Piping
await $`cat file.txt | grep "pattern" | wc -l`;

// Safe interpolation (auto-escaped)
const userInput = "file with spaces.txt";
await $`cat ${userInput}`;

// Options
await $`pwd`.cwd("/tmp");
await $`echo $FOO`.env({ FOO: "bar" });

// Suppress errors
const { stdout, exitCode } = await $`may-fail`.nothrow().quiet();

Process Spawning

For non-shell process control:

const proc = Bun.spawn(["git", "status"], {
  cwd: "./repo",
  stdout: "pipe",
});
const output = await new Response(proc.stdout).text();
await proc.exited;

Synchronous variant for simple cases:

const { stdout, success } = Bun.spawnSync(["echo", "hello"]);
console.log(stdout.toString());

Dependencies

bun add zod                    # runtime dependency
bun add -d @types/node         # dev dependency
bun remove unused-pkg          # remove
bunx prettier --write .        # run without installing

Bun can auto-install packages at runtime when no node_modules exists. For reproducible scripts, prefer explicit bun add.

Testing

Bun has a built-in Jest-compatible test runner. No extra packages needed.

// math.test.ts
import { expect, test, describe } from "bun:test";

test("addition", () => {
  expect(2 + 2).toBe(4);
});

test("async", async () => {
  const file = Bun.file("data.json");
  expect(await file.exists()).toBe(true);
});

bun test                              # run all tests
bun test --watch                      # re-run on changes
bun test --test-name-pattern "auth"   # filter by name
bun test specific.test.ts             # run one file

Test files are discovered automatically: *.test.ts, *.spec.ts, *_test.ts, *_spec.ts.

HTTP Server

Bun.serve({
  port: 3000,
  routes: {
    "/health": new Response("OK"),
    "/api/data": () => Response.json({ status: "ok" }),
    "/api/items/:id": req => Response.json({ id: req.params.id }),
  },
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});

SQLite

Built-in, no packages required:

import { Database } from "bun:sqlite";

const db = new Database("app.db");
db.run("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)");
db.run("INSERT INTO items (name) VALUES (?)", ["example"]);
const rows = db.query("SELECT * FROM items").all();

Key Patterns

1. Prefer Bun.file()/Bun.write() over node:fs — faster and simpler API.
2. Prefer Bun.$ over Bun.spawn() for shell commands — safer interpolation, cleaner syntax.
3. Use Bun.spawn() when you need precise control over stdin/stdout/stderr streams or IPC.
4. Import from "bun:test" not "jest" — the API is Jest-compatible but the import path differs.
5. Types are stripped, not checked. Bun never validates types at runtime. Run tsc --noEmit if you need type-checking (e.g., CI).

Gotchas

• Flag ordering: Bun flags go before run: bun --watch run dev (not bun run dev --watch).
• No type-checking at runtime: A script with type errors still executes. Use tsc --noEmit for validation.
• Lifecycle scripts are blocked by default: If a package needs postinstall, add it to trustedDependencies in package.json.
• The $ shell is not bash: It is Bun's own implementation. Use $(...) for command substitution (backticks don't work inside $).
• Auto-install has no Intellisense: Run bun install to populate node_modules for IDE support.

Further reading

1. Start with references/REFERENCE.md — offline, curated, covers the common surface area (file I/O, shell, spawn, serve, sqlite, test, config, CLI).

2. If REFERENCE.md doesn't cover it (new APIs, obscure flags, niche config, recently added features), fetch the official LLM-optimized docs dump:

   • Index: https://bun.sh/llms.txt
   • Full docs: https://bun.sh/llms-full.txt

   Prefer the index first to find the relevant section, then fetch the full file only if needed.