@arkenv/bun-plugin

Bun plugin to validate environment variables at build-time with ArkEnv.

Read the docs →

Features

• Build-time validation - app won't start if environment variables are invalid
• Typesafe environment variables backed by TypeScript
• Access to ArkType's powerful type system
• Automatic filtering of client-exposed variables (defaults to BUN_PUBLIC_* and NODE_ENV)

[!IMPORTANT] This plugin requires arktype to be installed in your project.

You can still use Zod or Valibot schemas alongside ArkType's DSL, since ArkType natively supports Standard Schema.

See the docs for details.

Installation

pnpm add @arkenv/bun-plugin arktype

npm install @arkenv/bun-plugin arktype

yarn add @arkenv/bun-plugin arktype

bun add @arkenv/bun-plugin arktype

Usage

Simple Setup (Auto-discover schema)

Create your schema in src/env.ts:

// src/env.ts
import { type } from 'arkenv';

export default type({
  BUN_PUBLIC_API_URL: 'string',
  BUN_PUBLIC_DEBUG: 'boolean',
  NODE_ENV: '"development" | "test" | "production" = "development"',
});

Configure for bun serve in bunfig.toml:

[serve.static]
plugins = ["@arkenv/bun-plugin"]

Configure for Bun.build in your build script:

// build.ts
import arkenv from '@arkenv/bun-plugin';

await Bun.build({
  entrypoints: ['./app.tsx'],
  outdir: './dist',
  plugins: [arkenv], // Auto-discovers src/env.ts
});

Advanced Setup

Pass your schema directly to the plugin:

// build.ts
import arkenv from '@arkenv/bun-plugin';
import { type } from 'arkenv';

await Bun.build({
  entrypoints: ['./app.tsx'],
  outdir: './dist',
  plugins: [
    arkenv(type({
      BUN_PUBLIC_API_URL: 'string',
      BUN_PUBLIC_DEBUG: 'boolean',
      NODE_ENV: '"development" | "test" | "production" = "development"',
    })),
  ],
});

With Type Augmentation

// src/env.d.ts
/// <reference types="bun-types" />

import type { ProcessEnvAugmented } from '@arkenv/bun-plugin';

declare global {
  namespace NodeJS {
    // Note: This assumes your env schema is the default export from "./env"
    interface ProcessEnv extends ProcessEnvAugmented<typeof import("./env").default> {}
  }
}

Examples

• bun-react

Related

• ArkEnv - Core library and docs
• ArkType - Underlying validator / type system