ArkEnv in `vite.config.ts`

[yamcodes]

Problem

There’s no clear documentation on how to use ArkEnv for non-prefixed environment variables (e.g., PORT) in vite.config.ts. This leads to confusion and missed opportunities for type-safe config in server-side Vite code.

Context

• By default, Vite only exposes VITE_-prefixed variables to client code, but vite.config.ts often needs access to unprefixed variables (like PORT, database creds, etc.).
• ArkEnv can provide strong typing and helpful errors in config files, but guidance is missing.
• See related: bug: vite typescript does not infer the environment variables type. #195 (client-side env), Vite docs.

Proposal

• Recommend and document best practices for using ArkEnv inside vite.config.ts with unprefixed variables.
• Implement any required additions, including potentially wrapping Vite's loadEnv with applied ArkEnv transformations and typing.
• Add a clear example and update docs to clarify the distinction between server-only (config) and client-exposed (VITE_*) environment usage.
• Optionally, add a sample or test to the examples folder.

Acceptance

• ArkEnv-based parsing for unprefixed vars in vite.config.ts is implemented.
• Docs clearly distinguish config/server-only and client env patterns.
• Example usage is included.

[yamcodes]

We have an challenge here where we need the schema AND the typing to be available in both the plugins section of the defineConfig object, AND around the loadEnv call so we can get transformed+typesafe envs. The trouble is that happens before the plugin is defined, so grabbing the typing from it is difficult. Also I'm not sure how the Vite flow works exactly but I'm not even sure we can apply plugins before loadEnv is used.

To remedy this, I thought of a factory solution:

import ArkEnv from "@arkenv/vite-plugin";
import React from "@vitejs/plugin-react";
import arkenv, { type } from "arkenv";
import { defineConfig } from "vite";

const arkenv = createArkEnv({
	PORT: "number.port",
	VITE_MY_VAR: "string",
	VITE_MY_NUMBER: type("string").pipe((str) => Number.parseInt(str, 10)),
	VITE_MY_BOOLEAN: type("string").pipe((str) => str === "true"),
});

// https://vite.dev/config/
export default defineConfig(({ mode }) => {
	const env = arkenv.loadEnv(mode, process.cwd(), "");
	return {
		plugins: [
			React(),
			arkenv.vitePlugin(),
		],
		server: {
			port: env.PORT,
		},
	};
});

This would certainly work because we are defining the schema before we are even granted the plugin OR doing env loading in the config definition. The trouble is that it's a little cubmersome and requires writing code outside of the defineConfig block, which some people might find not ideal.

Another approach which is more straightforward is to define the schema itself outside of the defineConfig block, and then just use it in both parts:

import ArkEnv, { loadEnv } from "@arkenv/vite-plugin";
import React from "@vitejs/plugin-react";
import arkenv, { type } from "arkenv";
import { defineConfig } from "vite";

const Env = type({
	PORT: "number.port",
	VITE_MY_VAR: "string",
	VITE_MY_NUMBER: type("string").pipe((str) => Number.parseInt(str, 10)),
	VITE_MY_BOOLEAN: type("string").pipe((str) => str === "true"),
});

// https://vite.dev/config/
export default defineConfig(({ mode }) => {
	const env = loadEnv(mode, process.cwd(), "", Env);
	return {
		plugins: [React(), ArkEnv(Env)],
		server: {
			port: env.PORT,
		},
	};
});

While again, this might be more straightforward, I think it's a little less convenient, as we have to move around Env a lot. It also massively goes against the way the core Node ArkEnv library works atm.

I'm not sure if there's a more ideal way or a silver bullet to somehow both define the schema in the Vite config and use it for both loading non-prefixed variables AND for the plugin (for prefixed variables).

---

The only other thing I'm thinking of is defining the envs in a src/env.ts file like the core library does:

import arkenv, { type } from "arkenv";

export const env = arkenv({
	HOST: "string.host",
	PORT: "number.port",
	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
	ALLOWED_ORIGINS: type("string[]").default(() => []),
	DEBUG: "boolean = true",
});

Then we can somehow take the typeof this export via type Envs = typeof import('./src/env').env and supply it to the loadEnv function which would, in turn, grab the types statically. Something like this for vite.config.ts:

import ArkEnv, { loadEnv } from "@arkenv/vite-plugin";
import React from "@vitejs/plugin-react";
import { defineConfig, loadEnv } from "vite";

// https://vite.dev/config/
export default defineConfig(({ mode }) => {
	const env = loadEnv<typeof import('./src/env').env>(mode, process.cwd(), "", "./src/env");
	return {
		plugins: [React(), ArkEnv("./src/env")],
		server: {
			port: env.PORT,
		},
	};
});

Then if we use a good default for the file's location (src/env.ts) it would look maybe like this:

import ArkEnv, { loadEnv } from "@arkenv/vite-plugin";
import React from "@vitejs/plugin-react";
import { defineConfig } from "vite";

// https://vite.dev/config/
export default defineConfig(({ mode }) => {
	const env = loadEnv<typeof import('./src/env').env>(mode, process.cwd(), "");
	return {
		plugins: [React(), ArkEnv()],
		server: {
			port: env.PORT,
		},
	};
});

Which isn't so bad at all. Heck, we can even make it look like this:

import ArkEnv from "@arkenv/vite-plugin";
import React from "@vitejs/plugin-react";
import { defineConfig, loadEnv } from "vite";

// https://vite.dev/config/
export default defineConfig(({ mode }) => {
	const env = loadEnv(mode, process.cwd(), "");
	return {
		plugins: [React(), ArkEnv()],
		server: {
			port: env.PORT,
		},
	};
});

Using type augmentation (see https://github.com/Julien-R44/vite-plugin-validate-env?tab=readme-ov-file#typing-importmetaenv) or other clever trickery like cleverly defining our loadEnv to (somehow) dynamically import the types from this file. (Not sure if that's possible but we can try)