Nuxt

@arkenv/nuxt validates environment variables on server and client routes, maps public keys onto Nuxt runtime config, and keeps server secrets off the browser.

For high-level architectural trade-offs, see Frameworks.

Quickstart

Scaffold Nuxt integration in an existing project using the CLI:

npx arkenv init

pnpm dlx arkenv init

yarn dlx arkenv init

bunx arkenv init

The CLI registers @arkenv/nuxt/module in your Nuxt config and creates your initial schema file.

Manual installation

If you prefer manual setup, install @arkenv/nuxt alongside your chosen validation engine.

ArkType engine

Install @arkenv/core and its peer dependency arktype:

npm install @arkenv/core @arkenv/nuxt arktype

pnpm add @arkenv/core @arkenv/nuxt arktype

yarn add @arkenv/core @arkenv/nuxt arktype

bun install @arkenv/core @arkenv/nuxt arktype

Standard Schema engine

If you aren't using ArkType, install @arkenv/standard:

npm install @arkenv/standard @arkenv/nuxt

pnpm add @arkenv/standard @arkenv/nuxt

yarn add @arkenv/standard @arkenv/nuxt

bun install @arkenv/standard @arkenv/nuxt

Module configuration

Register the module in your nuxt.config.ts. The module automatically injects runtime configuration and validates variables during build and development.

export default defineNuxtConfig({
  modules: ["@arkenv/nuxt/module"],
});

Schema

Use a single env.ts. Public keys must use the NUXT_PUBLIC_ prefix:

import arkenv from "@arkenv/nuxt";

export const env = arkenv({
  DATABASE_URL: "string",
  NUXT_PUBLIC_API_URL: "string = 'https://api.example.com'",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
});

Unlike Next.js, Nuxt does not emit an env.gen.ts file; @arkenv/nuxt acts as the primary entrypoint.

If you split client and server modules for name/type isolation, never import the server module from client or Vue code. See the two-module recipe.

Read env in application code

Import { env } from "./env".

Standard Schema

If you aren't using ArkType, point the module at the standard module path and import from @arkenv/nuxt/standard:

export default defineNuxtConfig({
  modules: ["@arkenv/nuxt/standard/module"],
});

Then define your schema in env.ts using your validator:

import arkenv from "@arkenv/nuxt/standard";
import * as z from "zod";

export const env = arkenv({
  DATABASE_URL: z.url(),
  NUXT_PUBLIC_API_URL: z.url().default("https://api.example.com"),
});

Nitro boot gate and runtimeConfig hydration

Containers in staging and production inject environment variables at startup rather than at build time.

Vite and Bun inline literals at build time through compile-time transforms. @arkenv/nuxt hooks into Nuxt's Nitro engine instead:

1. Server boot gate: At server startup, an internal Nitro plugin runs before route handlers execute. It validates the environment against your schema and throws fail-fast errors on invalid secrets.
2. Runtime configuration hydration: An internal Nitro plugin passes validated public variables (NUXT_PUBLIC_*) into useRuntimeConfig().public.
3. Client access: Client components read public values from runtime configuration during browser rendering and hydration, avoiding hardcoded build-time literals.

You can update environment variables across deployment stages without rebuilding client JavaScript bundles. Ship one image and change env at container start for staging versus production.

Unlike Next.js env.gen.ts, @arkenv/nuxt writes no generated files to commit or gitignore. The module validates at boot and registers public keys on runtimeConfig.

Next steps