FAQ

I was able to access a client-side variable in a server context! Is that ok?

Yes. In Nuxt, environment variables prefixed with NUXT_PUBLIC_ are public and intended to be accessible everywhere (both server-side and browser-side).

@arkenv/nuxt permits accessing client variables in server-side contexts (like server routes, middleware, or plugins) by design. The runtime security proxy only blocks the reverse: accessing server-only variables (those without the NUXT_PUBLIC_ prefix) on the client side.

Do I need to manually map client variables in runtimeEnv?

No. ArkEnv automates this mapping entirely via the @arkenv/nuxt/module configuration helper.

In other environment validation libraries, you must manually write a runtimeEnv mapping object containing keys like NUXT_PUBLIC_VAR: process.env.NUXT_PUBLIC_VAR so that the bundler can access and package them.

ArkEnv's Nuxt module scans your schema file(s) at build time, identifies the client-side and shared keys, and automatically registers them to Nuxt's runtimeConfig. You get the benefits of typesafe validation without manual mapping boilerplate.

How does the compile-time client security work?

In the strict layout, server-only schemas live in a separate file (for example, env/server.ts). If client-side code accidentally imports from that file, the build fails immediately with a clear compile-time error - before the code ever reaches the browser.

This guarantees that private server keys, validation schemas, and database constraints never ship in client bundles.

When should I use the strict layout?

If the flat layout is recommended, why use the strict layout?

1. Compile-time isolation: A custom Vite compiler plugin checks and blocks any client-side imports of server environments before the code runs.
2. Clean separation of concerns: Separating client schemas (client.ts) and server schemas (server.ts) naturally matches Nuxt's architectural boundaries (e.g. client components vs. server routes).
3. No boilerplate penalty: The ArkEnv CLI completely eliminates the setup effort. Running arkenv init --strict scaffolds the entire 3-file setup with the unified client and server factories pre-wired.

Can I deploy the same build to staging and production?

Yes. Because @arkenv/nuxt reads environment variables via Nuxt's useRuntimeConfig() at runtime instead of inlining them at build time, you can:

1. Run nuxt build once
2. Package the output (e.g. in a Docker image)
3. Deploy that same artifact to staging, QA, and production - changing only the environment variables at container startup

No application rebuild is required when values change. You can also use Nuxt's native override prefixes (e.g. NUXT_DATABASE_URL or NUXT_PUBLIC_API_URL) to swap values dynamically across environments.

Does @arkenv/nuxt generate any files I need to commit or .gitignore?

No. Unlike the Next.js integration (which writes an env.gen.ts helper due to webpack's static analysis requirements), the Nuxt integration generates zero files.

Nuxt resolves public runtime variables dynamically through useRuntimeConfig(), so there is no static runtimeEnv mapping to write. The module only:

1. Validates your schema at build/dev startup and throws descriptive errors for invalid or missing variables.
2. Registers public keys into Nuxt's runtimeConfig so they are available on both server and client.

You do not need to add anything to .gitignore, and there is no generated directory to keep in sync with your schema.