Defining your schema

ArkEnv is designed around one schema file and one typed env object. ArkEnv proves the process has the configuration it claims before application code runs, whether you use ArkType, Zod, or another Standard Schema validator.

Fail fast

Calling arkenv() parses the configured source immediately. Missing required keys or values that fail the schema throw ArkEnvError at the call site.

Framework adapters validate in builds by default. Only keys you declare appear on the returned object (onUndeclaredKey defaults to "delete"). env is a closed set of known fields, not leftover process variables.

Where env.ts lives

Install either engine, then create env.ts next to the code that boots first. Root of the app or package is common; src/env.ts is fine when the rest of your entrypoints already live under src/.

npm install @arkenv/core arktype

pnpm add @arkenv/core arktype

yarn add @arkenv/core arktype

bun install @arkenv/core arktype

import arkenv from "@arkenv/core";

export const env = arkenv({
  HOST: "string.host = 'localhost'",
  PORT: "number.port = 3000",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
});

npm install @arkenv/standard zod

pnpm add @arkenv/standard zod

yarn add @arkenv/standard zod

bun install @arkenv/standard zod

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

export const env = arkenv({
  HOST: z.string().default("localhost"),
  PORT: z.int().min(0).max(65535).default(3000),
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
});

Import that object from application code:

import { env } from "../env";

console.log(`listening on ${env.HOST}:${env.PORT}`);

What belongs in the schema

Put every variable your process reads into the schema: secrets, public keys, tunables, and platform vars you rely on.

• Required secrets (DATABASE_URL, API_KEY)
• Tunables with defaults (PORT, LOG_LEVEL)
• Framework public keys (NEXT_PUBLIC_*, VITE_*, NUXT_PUBLIC_*, BUN_PUBLIC_*)
• Hosting provider system variables (VERCEL_ENV, CONTEXT, …) when you use them

The ArkEnv CLI and hosting presets can inject the provider fields for you. You can still declare them by hand.

A single env.ts is the default layout for Node apps and flat layout frameworks:

Keep .env.example in sync with the schema so new contributors know which keys to set.

Strings, numbers, booleans, enums

Your schema is a map from env key names to validators. @arkenv/core uses the ArkType DSL (and ArkEnv keywords). @arkenv/standard accepts Zod, Valibot, and other Standard Schema validators. Pick one stack per project; both paths produce a typed env object.

Coercion and parsing covers how strings become numbers and booleans. This section is about declaring the shape.

import arkenv from "@arkenv/core";

export const env = arkenv({
  API_URL: "string",
  APP_NAME: "string = 'My App'",
  OPTIONAL_NOTE: "string | undefined",
  PORT: "number.port = 3000",
  RETRY_COUNT: "number.integer = 3",
  DEBUG: "boolean = false",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
  LOG_LEVEL: "'debug' | 'info' | 'warn' | 'error' = 'info'",
});

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

export const env = arkenv({
  API_URL: z.string(),
  APP_NAME: z.string().default("My App"),
  OPTIONAL_NOTE: z.string().optional(),
  PORT: z.int().min(0).max(65535).default(3000),
  RETRY_COUNT: z.int().default(3),
  DEBUG: z.boolean().default(false),
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

ArkEnv keywords (ArkType)

@arkenv/core adds env-oriented keywords on top of ArkType's primitives. They are not available on @arkenv/standard.

import arkenv from "@arkenv/core";

export const env = arkenv({
  HOST: "string.host = 'localhost'",
  PORT: "number.port = 3000",
});

Full details: keywords.

Typesafety

The schema is the single source of truth for runtime checks and TypeScript types.

import arkenv, { type Infer } from "@arkenv/core";

const schema = {
  DATABASE_URL: "string",
  PORT: "number.port = 3000",
} as const;

export const env = arkenv(schema);
export type Env = Infer<typeof schema>;

env.PORT; // number

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

const schema = {
  DATABASE_URL: z.url(),
  PORT: z.int().min(0).max(65535).default(3000),
};

export const env = arkenv(schema);
export type Env = typeof env;

env.PORT; // number

Typesafety holds when application code imports env and validation runs at boot or build. Casting process.env, or skipping the import, bypasses it. Types do not load .env files.

Flat layouts may expose server key names to client TypeScript while blocking values. Strict layouts keep server modules out of the client graph. See Client vs. server.

Richer field definitions

For transforms, function defaults, or reuse across files:

import arkenv, { type } from "@arkenv/core";

export const env = arkenv({
  PORT: "number.port = 3000",
  FEATURE_FLAGS: type("string[]").default(() => []),
  BUILD_ID: type("string").pipe((value) => value.trim()),
});

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

export const env = arkenv({
  PORT: z.int().min(0).max(65535).default(3000),
  BUILD_ID: z.string().transform((value) => value.trim()),
});

See Transforms for morph vs Zod .transform, and reusing schemas when the whole schema should be shared.

Custom env source

By default arkenv() reads process.env. Pass a custom record for tests, Workers bindings, or any host that injects env outside process.env:

import arkenv from "@arkenv/core";

export const env = arkenv(
  { PORT: "number.port" },
  { env: { PORT: "3000" } },
);

Framework plugins (Next.js, Nuxt, Vite, Bun) wire the usual sources for you. See options for coerce, arrayFormat, emptyAsUndefined, and safe.

What ArkEnv owns vs your schema library

ArkEnv loads the input record, optionally coerces strings, then hands the result to your schema library. Field rules always come from that library:

See Validators for packaging and peer-dependency differences.

Next steps