Strict layout

In this setup, you define your client and server schemas in separate files. An optional internal/shared.ts holds variables shared by both.

By importing env from ~/env/client in client-side code and ~/env/server in server-side code, you enforce a strict boundary where server variables and schemas never leak to the browser. If ~/env/server is accidentally imported on the client side, ArkEnv fails the build with a compilation error. See the Security model page for more details.

Setup

The easiest way to bootstrap the strict layout is with the ArkEnv CLI. It automatically configures @arkenv/nuxt for your existing Nuxt project using the strict layout option.

npx @arkenv/cli@latest init --strict

pnpm dlx @arkenv/cli@latest init --strict

yarn dlx @arkenv/cli@latest init --strict

bunx @arkenv/cli@latest init --strict

Your schema

When bootstrapping with the CLI, it generates separate schema files under env/ (including an optional internal/shared.ts with NODE_ENV for convenience):

import { type } from "@arkenv/nuxt/shared";

/**
 * @internal 🛑 INTERNAL SCHEMA ONLY.
 * Do not import this directly. Import `env` from `./client` or `./server` instead.
 */
export const SharedSchema = type({
	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
});

import arkenv from "@arkenv/nuxt/client";
import { SharedSchema } from "./internal/shared";

export const env = arkenv(
	{
		NUXT_PUBLIC_API_URL: "string = 'https://api.example.com'",
	},
	{
		extends: [SharedSchema],
	},
);

import arkenv from "@arkenv/nuxt/server";
import { env as clientEnv } from "./client";

export const env = arkenv(
	{
		DATABASE_URL: "string",
	},
	{
		extends: [clientEnv],
	},
);

Usage

Both env/client.ts and env/server.ts export the resolved environment as env. This lets you use consistent env.MY_VAR imports depending on where the code executes.

In server code (server routes, middleware)

Import env from the server file. It contains all public, shared, and server-only variables:

import { env } from "~~/env/server";

export default function defineEventHandler(event: unknown) {
	// Access database URL and client API URL safely
	const db = env.DATABASE_URL;
	const api = env.NUXT_PUBLIC_API_URL;
	return { api };
}

In client-side code

Import env from the client file (env/client.ts). The boundary protection works at two levels:

1. TypeScript type safety: If you import env from the client file and try to access a server-side variable (like DATABASE_URL), you will get a TypeScript compilation error because it is not defined in the client-safe schema:

import { env } from "~~/env/client";

const api = env.NUXT_PUBLIC_API_URL;
const db = env.DATABASE_URL;
Property 'DATABASE_URL' does not exist on type 'Readonly<{ NUXT_PUBLIC_API_URL: string; } & { NODE_ENV: "development" | "production" | "test"; }>'.

2. Compile-time isolation: If you accidentally import env from the server file (env/server.ts) in client-side code, the build fails with a compilation error before the code ever runs.