Configuration & API
API reference and configuration options for @arkenv/nextjs.
Register ArkEnv in your Next.js config
The idiomatic way to use ArkEnv in Next.js is the withArkEnv config wrapper. It runs ArkEnv's codegen and validation as part of the Next.js build lifecycle and returns your config object unchanged.
import { } from "@arkenv/nextjs/config";
import type { NextConfig } from "next";
const : NextConfig = {
/* config options here */
};
export default ();By default, ArkEnv looks for your schema in src/env.ts or env.ts and writes the generated helper to [schemaDirectory]/generated/env.gen.ts.
Custom paths
Pass options as the second argument:
import { } from "@arkenv/nextjs/config";
import type { NextConfig } from "next";
const : NextConfig = {};
export default (, {
: "src/env/my-schema.ts",
: "src/generated/my-env.gen.ts",
});Configuration options
The withArkEnv() wrapper accepts the following options:
Prop
Type
Specify the path to the schema definition file.
Defaults to searching for "src/env.ts" or "env.ts" in the project root.
Type
string | undefined
Default
"src/env.ts"
Specify the path where the generated file (env.gen.ts) should be written.
Defaults to "generated/env.gen.ts" in the same directory as the schema file.
Type
string | undefined
Default
"[schemaDirectory]/generated/env.gen.ts"
Specify the configuration layout.
"flat"(default): A singleenv.tsschema file."strict": A split schema layout (env/client.ts,env/server.ts, and optionallyenv/internal/shared.ts).
Type
"flat" | "strict" | "simple" | undefined
Default
"flat"
Enable or disable build-time environment variable validation during build/dev startup.
Type
boolean | undefined
Default
true
Enable or disable automatic code generation of the env.gen.ts file.
Type
boolean | undefined
Default
true
Avoiding wrapper bloat
Disabling codegen
By default, ArkEnv generates an env.gen.ts helper so you don't have to write a manual runtimeEnv mapping. If you prefer to opt out of codegen entirely, you can. This is useful if you want full control over the runtimeEnv object or are working in an environment where file generation is undesirable.
Pass the --no-codegen flag when bootstrapping with the CLI:
npx @arkenv/cli@latest init --no-codegenOr set it up manually by passing the { codegen: false } option to withArkEnv in next.config.ts, and importing createEnv directly from @arkenv/nextjs in your schema file. You then become responsible for keeping runtimeEnv in sync with your schema.
Build-time validation without codegen
When using { codegen: false }, withArkEnv will skip compiling and generating env.gen.ts but will still execute build-time environment variable validation, ensuring invalid variables fail the build:
import { } from "@arkenv/nextjs/config";
import type { NextConfig } from "next";
const : NextConfig = {};
export default (, { : false });See the FAQ for the full manual setup pattern.
Components
<ArkEnvScript />
Used to inject public client-side variables dynamically during server-side rendering (SSR), enabling support for runtime environment configuration changes in containerized deployments.
Import
import { ArkEnvScript } from "@arkenv/nextjs";Usage
Insert it inside the <body> of your root layout (app/layout.tsx):
import { ArkEnvScript } from "@arkenv/nextjs";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<ArkEnvScript />
{children}
</body>
</html>
);
}