Pure Bun-native filesystem utilities from @side-quest/core/fs. Use when you need command-injection-safe filesystem operations, prefer Bun over node:fs, or want token-efficient fs helpers. All functions use Bun.spawn, Bun.file(), or Bun.write() - no node:fs dependencies.
View on GitHubnathanvale/side-quest-marketplace
dev-toolkit
February 4, 2026
Select agents to install to:
npx add-skill https://github.com/nathanvale/side-quest-marketplace/blob/main/plugins/dev-toolkit/skills/bun-fs-helpers/SKILL.md -a claude-code --skill bun-fs-helpersInstallation paths:
.claude/skills/bun-fs-helpers/# Bun Filesystem Helpers
Pure Bun-native filesystem utilities from `@side-quest/core/fs` - zero node:fs dependencies, command-injection safe.
## When to Use
- **Writing new code** - Always prefer these over node:fs
- **Command injection concerns** - All shell commands use array args (safe)
- **Token efficiency** - Smaller imports, faster operations
- **Bun-first projects** - Leverages Bun's native APIs
## Available Functions
### File Existence
```typescript
import { pathExists, pathExistsSync } from "@side-quest/core/fs";
// Async
if (await pathExists("/path/to/file")) { }
// Sync
if (pathExistsSync("/path/to/file")) { }
```
**Implementation**: Uses `Bun.file().exists()` (async) or `test -e` command (sync)
### Reading Files
```typescript
import { readTextFile, readTextFileSync, readJsonFile, readJsonFileSync } from "@side-quest/core/fs";
// Async text
const content = await readTextFile("/path/to/file.txt");
// Sync text
const content = readTextFileSync("/path/to/file.txt");
// Async JSON
const data = await readJsonFile<MyType>("/path/to/data.json");
// Sync JSON
const data = readJsonFileSync<MyType>("/path/to/data.json");
```
**Implementation**: Uses `Bun.file().text()` (async) or `cat` command (sync)
### Writing Files
```typescript
import { writeTextFile, writeTextFileSync, writeJsonFile, writeJsonFileSync } from "@side-quest/core/fs";
// Async text
await writeTextFile("/path/to/file.txt", "content");
// Sync text
writeTextFileSync("/path/to/file.txt", "content");
// Async JSON
await writeJsonFile("/path/to/data.json", { foo: "bar" }, 2);
// Sync JSON
writeJsonFileSync("/path/to/data.json", { foo: "bar" }, 2);
```
**Implementation**: Uses `Bun.write()` (async) or `printf` via shell (sync)
### Directory Operations
```typescript
import { ensureDir, ensureDirSync, readDir, readDirAsync } from "@side-quest/core/fs";
// Create directory (recursive)
await ensureDir("/path/to/nested/dir");
ensureDirSync("/path/to/nested/dir");
// List directory