Strict layout

In this setup, you define your client, server, and shared schemas in separate files.

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.

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 three separate schema files under env/:

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;
// @ts-expect-error DATABASE_URL is not defined in client env
const db = env.DATABASE_URL;

2. Compile-time isolation: If you accidentally import env from the server file (env/server.ts) in client-side code, Nuxt's Vite bundler will fail the build with a compilation error. This is because @arkenv/nuxt registers a custom Vite plugin that detects imports of the server module on the client side and blocks them at build time.