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

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

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)

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 arkenv from "@arkenv/bun-plugin";
import { type } from "arkenv";
import { z } from "zod";

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

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. 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 (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, you should also install arktype:

npm install arktype

pnpm add arktype

yarn add arktype

bun add arktype