Introduction

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.

Usage

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

1. Create your schema

import { type } from "arkenv/arktype";

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

2. Configure for Bun.serve (dev mode)

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

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

Advanced setup

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/arktype";

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/arktype";

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

export default arkenv(Env);

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

Validator Mode

By default, ArkEnv uses ArkType for validation. However, you can use any Standard Schema compatible library (like Zod or Valibot) by setting the validator option to "standard".

In this mode, you don't need to install arktype.

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

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

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.

Installation

npm install @arkenv/bun-plugin arkenv

pnpm add @arkenv/bun-plugin arkenv

yarn add @arkenv/bun-plugin arkenv

bun add @arkenv/bun-plugin arkenv

If you intend to use the default validator mode, you should also install arktype:

npm install arktype

pnpm add arktype

yarn add arktype

bun add arktype