Introduction

Features

• Static Analysis: Validates environment variables against your schema and configures Vite's define behavior to expose them via import.meta.env.VARIABLE, leaving the actual inlining to Vite.
• Typesafety: Ensures your code only accesses variables defined in your schema.
• Secure Defaults: Only exposes variables prefixed with VITE_ to the client bundle. NODE_ENV is also exposed when defined in your schema.

Quickstart

1. Installation

npm install @arkenv/vite-plugin arkenv arktype

pnpm add @arkenv/vite-plugin arkenv arktype

yarn add @arkenv/vite-plugin arkenv arktype

bun add @arkenv/vite-plugin arkenv arktype

2. Configure Plugin

Define your schema as an exported constant in vite.config.ts. This allows the schema to be imported for typesafety in other files.

import arkenv from "@arkenv/vite-plugin";
import { type } from "arkenv";
import { defineConfig } from "vite";

export const Env = type({
	PORT: "number.port",
	VITE_MY_VAR: "string"
});

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

3. Add Typesafety

To make import.meta.env fully typesafe, add the following to src/vite-env.d.ts:

/// <reference types="vite/client" />

type ImportMetaEnvAugmented = import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
	typeof import("../vite.config").Env
>;

interface ImportMetaEnv extends ImportMetaEnvAugmented {}

interface ImportMeta {
	readonly env: ImportMetaEnv;
}

4. Use in your code

You can now use import.meta.env with full typesafety and autocompletion throughout your application.

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

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)

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

For advanced workflows, see using ArkEnv in Vite config.