ezBun

Make running Bun sandboxes easy. ezbun is a CLI tool that scans your project for scripts and provides an interactive menu to run them. It also includes built-in environment variable validation and type generation.

Terminal

% bun dev_

Get started Github NPM

Features

Interactive Menu

Select scripts to run via a CLI interface.

Env Validation

Validates environment variables using Zod before running scripts.

Type Safety

Automatically generates env.d.ts for type-safe process.env.

Watch Mode

Supports running scripts in watch mode.

Installation

bun add -D ezbun

Usage

Without direct installation with bunx:

bunx ezbun

Installed into your project:

bun ezbun

Tip. you can add a script to your package.json:

package.json

{
  "scripts": {
    "dev": "ezbun --watch", // with hot reloading
    "start": "ezbun"
  }
}

Then run:

bun dev

Watch Mode

You can run scripts in watch mode (hot reloading) by passing the --watch flag:

bun ezbun --watch

Configuration

Create an optional ezbun.config.ts file in your project root to customize behavior:

ezbun.config.ts

import { defineConfig } from "ezbun";

export default defineConfig({
  /** Source directory to scan for scripts */
  sourceDir: "./src", // default: "./src"

  /** File extensions to include */
  extensions: ["ts", "tsx", "js", "jsx"], // default: ["ts", "tsx", "js", "jsx", "cjs", "mjs"]

  /** Whether to show a success message after loading env vars */
  showSuccessMessage: false, // default: false
});

Environment Variables

ezbun makes handling environment variables easy and type-safe.

1. Create an env.schema.ts file in your project root:

env.schema.ts

import { defineEnv, z } from "ezbun";

export default defineEnv({
  DATABASE_URL: z.url().startsWith("postgres://"),
  API_KEY: z.string().startsWith("sk-"),
  PORT: z.coerce.number(),
});

2. When you run a script via ezbun, it will:

Validate process.env against your schema.
Print helpful error messages if validation fails.
Automatically generate env.d.ts for global type definitions.

Now you can use process.env with full type safety in your code!

/** typed as `string` not `string | undefined` */
console.log(process.env.API_KEY);