@arkenv/rsbuild-plugin

@arkenv/rsbuild-plugin validates env.ts during an Rsbuild compile and 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 TanStack Start 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/rsbuild-plugin
npm install @arkenv/core arktype

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

npm install -D @arkenv/rsbuild-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`	`PUBLIC_`	Keys exposed to the client
`logger` / `logLevel`	(none)	Logging

The plugin validates the environment loaded for that build: Rsbuild 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.

Tests and programmatic builds

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

import { createRsbuild } from "@rsbuild/core";
import arkenvPlugin from "@arkenv/rsbuild-plugin";

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

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

Next steps

TanStack Start framework guide

Setup recipes for Vite and Rsbuild, server functions, and client boundary.