@arkenv/vite-plugin

@arkenv/vite-plugin validates env.ts while Vite resolves config, then rewrites the client graph so public keys inline and server keys throw. This page is the export and option list. Setup recipes live in the Vite 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/vite-plugin
npm install @arkenv/core arktype

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

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

Exports

The default export and the named arkenvPlugin export are the same factory. Zod and Valibot import ./standard, which binds @arkenv/standard.

Export	Role
default	`arkenvPlugin` plugin factory
named `arkenvPlugin`	Plugin factory
`./standard`	Standard Schema plugin entry

Transform options

Pass transform options only. A schema argument is rejected.

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

The plugin validates the environment loaded for that build: Vite's env files, with variables already set on process.env winning.

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.

Call arkenvPlugin() with no args, or an options object that includes transform fields (schemaPath, clientPrefix, logging). Do not pass a schema map or compiled type() to the plugin.

Startup validation

When the plugin is registered, it resolves env.ts and validates it during Vite config resolution. Missing or invalid environment variables therefore abort the dev server or production build before Vite is ready. The plugin revalidates the schema when a relevant .env file or schema module changes during HMR.

Without the plugin, validation runs when a module imports env.ts. There is no default-off lazy-validation flag.

Tests and programmatic builds

Tests and scripts often call build() in a process that already loaded a .env file. To give one compile different values, set them on process.env before the build. Vite lets those values win over env files, and the plugin validates that loaded environment.

import { build } from "vite";
import arkenvPlugin from "@arkenv/vite-plugin";

const previous = process.env.VITE_API_URL;
process.env.VITE_API_URL = "https://staging.example.com";
try {
  await build({ plugins: [arkenvPlugin()] });
} finally {
  if (previous === undefined) delete process.env.VITE_API_URL;
  else process.env.VITE_API_URL = previous;
}

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

Next steps

Vite framework guide

Quickstart, transform mode, and reading env in application code.