Introduction

The ArkEnv Bun plugin validates your environment variables against your schema when running or building your application. It is specifically designed to work seamlessly with the Bun fullstack dev server (Bun.serve) and the Bun bundler (Bun.build). If a variable is missing or invalid, it immediately halts execution with a detailed validation error.

To keep client bundles secure, only variables prefixed with BUN_PUBLIC_ (and NODE_ENV if defined in the schema) are exposed to client-side code. The plugin configures Bun's compiler to inline these variables under process.env with full typesafety, and you can easily customize the public prefix in your configuration if needed.

Quickstart

The easiest way to get started is with the ArkEnv CLI. It automatically configures @arkenv/bun-plugin for your existing Bun project, or spins up a new one from a template.

npx @arkenv/cli@latest init

pnpm dlx @arkenv/cli@latest init

yarn dlx @arkenv/cli@latest init

bunx @arkenv/cli@latest init

Custom schema location

If you need to customize the schema location or prefer explicit configuration:

For Bun.build

Pass your schema directly to the plugin function:

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

const Env = type({
  BUN_PUBLIC_API_URL: "string",
  BUN_PUBLIC_DEBUG: "boolean",
});

await Bun.build({
  entrypoints: ["./app.tsx"],
  outdir: "./dist",
  plugins: [arkenv(Env)],
});

For Bun.serve

Create a custom plugin file and reference it in bunfig.toml:

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

const Env = type({
  BUN_PUBLIC_API_URL: "string",
  BUN_PUBLIC_DEBUG: "boolean",
});

export default arkenv(Env);

[serve.static]
plugins = ["./plugins/arkenv.ts"]

Using Standard Schema validators (Zod, Valibot, etc.)

This plugin uses ArkType for validation, which natively supports Standard Schema. You can freely mix ArkType DSL strings with Zod or Valibot validators in the same schema - no extra configuration needed.

import { type } from "arkenv";
import { z } from "zod";

export default type({
  BUN_PUBLIC_API_URL: z.string().url(),
  BUN_PUBLIC_DEBUG: "boolean",
});

const apiUrl = process.env.BUN_PUBLIC_API_URL;
       
const apiUrl: string