Introduction

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

Important

This plugin requires ArkType to be installed.

Features

Static Analysis: Validates environment variables against your schema and configures Bun's define behavior to expose them via process.env.VARIABLE, leaving the actual inlining to Bun.
Typesafety: Ensures your code only accesses variables defined in your schema.
Secure Defaults: Only exposes variables prefixed with BUN_PUBLIC_ to the client bundle. NODE_ENV is also exposed when defined in your schema. You can customize this prefix by setting the env option in your Bun.build() configuration.

Quickstart

1. Installation

npm install @arkenv/bun-plugin arkenv arktype

pnpm add @arkenv/bun-plugin arkenv arktype

yarn add @arkenv/bun-plugin arkenv arktype

bun add @arkenv/bun-plugin arkenv arktype

2. Configure Plugin

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).

Create your schema

src/env.ts

import {  } from "arkenv";

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

Configure for Bun.serve (dev mode)

bunfig.toml

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

Configure for Bun.build (build mode)

build.ts

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

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

3. Add Typesafety

To make process.env fully typesafe, see the Typing process.env guide to complete your setup.

4. Use in your code

You can now use process.env with full typesafety and autocompletion throughout your application.

src/App.tsx

const apiUrl = ..;       
const apiUrl: string

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:

build.ts

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:

plugins/arkenv.ts

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);

bunfig.toml

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

Using Standard Schema validators (Zod, Valibot)

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.

Note

When using external validators like Zod or Valibot, you must install them separately. For example, to use the z symbol from "zod" shown below, run npm install zod (or use valibot instead).

src/env.ts

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

export default ({
  : .().(),
  : "boolean",
});

src/App.tsx

const apiUrl = ..;       
const apiUrl: string

On this page