@arkenv/bun-plugin

@arkenv/bun-plugin rewrites env.ts in a Bun client bundle so BUN_PUBLIC_ keys inline and server keys throw. Backend-only scripts skip it and call @arkenv/core directly. This page is the export and option list. Setup recipes live in the Bun guide.

Installation

Install the plugin as a dev dependency next to the engine you write schemas with. The plugin does not bundle @arkenv/core or @arkenv/standard.

npm install -D @arkenv/bun-plugin
npm install @arkenv/core arktype

Or if you use Zod, Valibot, or another Standard Schema validator:

npm install -D @arkenv/bun-plugin
npm install @arkenv/standard

Exports

Export	Role
default	`arkenvPlugin` factory and plugin instance
named `arkenvPlugin`	Factory and zero-config plugin instance
`./standard`	Standard Schema plugin entry

arkenvPlugin is both a factory (arkenvPlugin({ schemaPath })) and a BunPlugin object with name, target, and setup. You can preload in bunfig.toml (plugins = ["@arkenv/bun-plugin"]), register in Bun.build, or pass transform options. Default client prefix: BUN_PUBLIC_.

Transform options

Same transform call shape as @arkenv/vite-plugin:

Option	Default	Meaning
`schemaPath`	auto (`env.ts`)	Schema module to transform
`clientPrefix`	`BUN_PUBLIC_`	Keys exposed to the client
`logger` / `logLevel`	(none)	Logging

The plugin validates process.env for that build.

Runtime options stay on arkenv()

Set env, coerce, onUndeclaredKey, arrayFormat, emptyAsUndefined, debugSecrets, and toJsonSchema on arkenv() in env.ts. The plugin rejects them. See Options.

A schema argument is rejected. Plugin config has no safe mode — failed validation cannot soft-fail into the bundle.

Tests and programmatic builds

Tests and scripts often call Bun.build() in a process that already has environment variables set. The plugin reads process.env, so assign the values for that compile before the build.

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

const previous = process.env.BUN_PUBLIC_API_URL;
process.env.BUN_PUBLIC_API_URL = "https://staging.example.com";
try {
  await Bun.build({
    entrypoints: ["./src/index.ts"],
    plugins: [arkenvPlugin],
  });
} finally {
  if (previous === undefined) delete process.env.BUN_PUBLIC_API_URL;
  else process.env.BUN_PUBLIC_API_URL = previous;
}

Restore the previous value in finally. The next compile in the same process then sees the original environment.

Next steps

Bun framework guide

Quickstart, fullstack setup, and reading env in application code.