Introduction

Link to section: what-is-this#What is this?

The ArkEnv plugin for Bun lets you validate environment variables at build-time and runtime with ArkEnv.

It supports a simple setup for most projects, automatically discovering your schema from ./src/env.ts or ./env.ts.

Link to section: usage#Usage

Link to section: simple-setup-recommended#Simple setup (recommended)

The simple setup automatically discovers your schema from src/env.ts or env.ts. This requires configuration in both bunfig.toml (for Bun.serve) and your build script (for Bun.build).

Link to section: 1-create-your-schema#1. Create your schema

import { type } from "arkenv";

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

Link to section: 2-configure-for-bunserve-dev-mode#2. Configure for Bun.serve (dev mode)

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

Link to section: 3-configure-for-bunbuild-build-mode#3. Configure for Bun.build (build mode)

import arkenv from "@arkenv/bun-plugin";

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

Link to section: advanced-setup#Advanced setup

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

Link to section: for-bunbuild#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)],
});

Link to section: for-bunserve#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"]

Link to section: features#Features

• Static Analysis: Automatically replaces process.env.VARIABLE with validated values during the build.
• Typesafety: Ensures your code only accesses variables defined in your schema.
• Secure Defaults: Only exposes variables prefixed with BUN_PUBLIC_ to the client bundle. You can customize this prefix by setting the env option in your Bun.build() configuration (e.g., env: "MY_PUBLIC_*" to use MY_PUBLIC_ instead). See Bun's bundler documentation for more details.

Link to section: installation#Installation

npm install @arkenv/bun-plugin arkenv arktype