Installation
Install ArkEnv with the CLI or by hand in a new or existing project.
Prerequisites
- Node.js: Active or Maintenance LTS.
- Package manager: npm, pnpm, Yarn, or Bun (required for the interactive CLI).
ArkEnv is designed to drop into a new or existing TypeScript app. ArkEnv provides an interactive CLI that detects your stack, writes a schema, and wires framework config.
npx arkenv initpnpm dlx arkenv inityarn dlx arkenv initbunx arkenv initOmit a project name to mutate the current directory. Pass a name to
create a new folder (optionally from --example):
npx arkenv init my-app --example with-vite-react -H vercelpnpm dlx arkenv init my-app --example with-vite-react -H vercelyarn dlx arkenv init my-app --example with-vite-react -H vercelbunx arkenv init my-app --example with-vite-react -H vercelFor agent sessions, use --agent (implies --yes --quiet --json):
npx arkenv init --agentpnpm dlx arkenv init --agentyarn dlx arkenv init --agentbunx arkenv init --agentLocal installation (recommended workflow)
Install the runtime validation engine as a dependency, and the arkenv CLI as a devDependency:
npm install @arkenv/core
npm install -D arkenvpnpm add @arkenv/core
pnpm add -D arkenvyarn add @arkenv/core
yarn add --dev arkenvbun install @arkenv/core
bun install --dev arkenvIf you are using Standard Schema (Zod or Valibot):
npm install @arkenv/standard
npm install -D arkenvpnpm add @arkenv/standard
pnpm add -D arkenvyarn add @arkenv/standard
yarn add --dev arkenvbun install @arkenv/standard
bun install --dev arkenvWhy install locally?
- Deterministic versioning: Locks the exact CLI version in
package-lock.jsonorpnpm-lock.yaml, ensuring absolute consistency across team members and CI pipelines. - Zero latency & offline execution: Executions run instantly from
node_modules/.bin/arkenvwithout querying npm, working completely offline. - CI/CD reliability: Pipelines execute the version frozen in the lockfile instead of dynamically resolving
@latest.
Once installed locally, running npx arkenv <command> (or pnpm arkenv, bun arkenv) inside your project automatically executes your locked local binary from node_modules/.bin.
Wire into package.json scripts
Add arkenv check to your project scripts to validate environment variables before builds:
{
"scripts": {
"build": "arkenv check && next build",
"env:check": "arkenv check"
}
}Flags, output files, and refusal codes live in
init reference.
Add to an existing repository
When the CLI finds a package.json, it adopts the repo incrementally.
Run the interactive CLI
npx arkenv initpnpm dlx arkenv inityarn dlx arkenv initbunx arkenv initThe CLI refuses a dirty git working tree. Commit or stash
(git stash -u) first, or pass
--force if you accept overwriting
generated files.
The CLI never reads your actual .env files. Suggested schema
key names come from .env.example if you have one, otherwise from
process.env / import.meta.env usage in source.
Answer the wizard
The CLI asks about framework, layout, validator, and hosting preset.
If compilerOptions.strict is off in tsconfig.json, the wizard
offers to enable it (recommended).
Review generated files
After the CLI, a Next.js app (for example) looks like this:
If the project has a src/ directory, the schema lands at
src/env.ts instead.
Import env in your app
If you don't have a .env file yet, copy the example and fill in
values:
cp .env.example .envImport env instead of process.env (or import.meta.env):
import { } from "../env";
.(.);Manual installation
Prefer a hands-on setup? Install the validation engine yourself, then add a framework package from the framework guides.
Validation engine
@arkenv/core is the ArkType-powered engine.
arktype is a required peer.
npm install @arkenv/core arktypepnpm add @arkenv/core arktypeyarn add @arkenv/core arktypebun install @arkenv/core arktypeIf you aren't using ArkType, install
@arkenv/standard:
npm install @arkenv/standardpnpm add @arkenv/standardyarn add @arkenv/standardbun install @arkenv/standardTypeScript module resolution
@arkenv/standard subpath exports (/valibot, /zod-mini) and the
framework plugin subpaths require modern TypeScript module resolution.
Set compilerOptions.moduleResolution to "bundler", "node16", or
"nodenext". Legacy "node" resolution is not supported.