Introduction

The ArkEnv Vite plugin integrates directly into Vite's build pipeline to validate your environment variables against your schema. If a variable is missing or fails validation, the plugin will halt the build or dev server immediately with a clear error message.

By matching Vite's default security model, only variables prefixed with VITE_ (along with NODE_ENV if included in your schema) are exposed to your client bundle. The plugin handles the underlying compiler configuration so you get complete autocomplete and typesafety when accessing import.meta.env across your project.

Quickstart

The easiest way to get started is with the ArkEnv CLI. It automatically configures @arkenv/vite-plugin for your existing Vite project, or spins up a new one from a template.

npx @arkenv/cli@latest init

pnpm dlx @arkenv/cli@latest init

yarn dlx @arkenv/cli@latest init

bunx @arkenv/cli@latest init

With this setup, if any environment variable is missing or invalid, your dev server won't start and your production build will fail with an error:

ArkEnvError: Errors found while validating environment variables
  VITE_MY_VAR must be a string (was missing)
  PORT must be an integer between 0 and 65535 (was "hello")

Using Standard Schema validators (Zod, Valibot, etc.)

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

export const Env = type({
	VITE_API_URL: z.string().url(),
	VITE_API_KEY: z.string().min(1),
	VITE_DEBUG: "boolean"
});

export default defineConfig({
	plugins: [arkenv(Env)]
});

const apiUrl = import.meta.env.VITE_API_URL;
       
const apiUrl: string

// Autocomplete works out-of-the-box!
const typing = import.meta.env.
BASE_URL
DEV
MODE
PROD
SSR
VITE_API_KEY
VITE_API_URL
VITE_DEBUG

For advanced workflows, see using ArkEnv in Vite config.