Arkenv

ArkEnv

ArkEnv is a typesafe environment variable validation library for modern JavaScript and TypeScript frameworks. It provides a single canonical surface across all frameworks: import { env } from "./env".

In v1, ArkEnv offers two first-class validation engines:

• @arkenv/core: Built-in ArkType DSL engine for high-performance schema definition and automatic coercion.
• @arkenv/standard: Standard Schema engine supporting any compliant validator (Zod, Valibot, etc.).

Capabilities

Core usage

• Define typesafe schemas using @arkenv/core ArkType DSL strings or @arkenv/standard with Zod / Valibot.
• Automatic coercion (string.numeric, number.port, booleans, JSON objects, arrays) and default values ("boolean = true").
• Single, uniform developer experience: import env directly across frontend and backend code.

Framework integration

• Vite (@arkenv/vite-plugin): Plugin operates in transform mode, rewriting imports from env.ts in the client graph to inline public VITE_* literals and replacing private server keys with throwing runtime guards.
• Bun (@arkenv/bun-plugin): Plugin intercepts env.ts imports in Bun.build / Bun.serve to inline public BUN_PUBLIC_* values while guarding server secrets.
• Next.js (@arkenv/nextjs): Build-time and runtime validation with automatic client/server isolation proxy.
• Nuxt (@arkenv/nuxt): Nuxt module with Nitro boot validation and runtime proxy guard.
• Node.js: Direct boot-time validation via @arkenv/core or @arkenv/standard.

CLI (setup & DevOps)

• Initialize ArkEnv in new or existing projects using pnpm dlx arkenv init (or npx arkenv init).
• Automatically detect frameworks (Next.js, Nuxt, Vite, Bun, etc.) and scaffold env.ts.
• Select hosting provider preset during init (--preset, -P <provider>).
• Automatically configure tsconfig.json when needed. Schema discovery for CLI commands uses --schema or flat convention paths (env.ts, src/env.ts) — not a package.json "arkenv" field, and not leftover split-layout filenames such as env/server.ts.

Hosting presets

ArkEnv is code-first. You can select a hosting provider preset during initial project setup (--preset vercel, netlify, cloudflare, railway, render, fly) or copy-paste provider fields directly into ./env.ts from the documentation (/docs/core-concepts/hosting-presets). There are no machine-managed comment blocks or CLI mutation commands.

Agent setup (machine-readable)

AI agents SHOULD always use the CLI for project initialization to ensure consistency and reliability. Use the --agent flag for a fully automated, machine-readable experience.

• Command: pnpm dlx arkenv init --agent
• Behavior: The --agent flag automatically enables the following behaviors:
  • --yes: Bypasses all interactive prompts and uses recommended defaults.
  • --quiet: Suppresses spinners and ANSI formatting for cleaner terminal logs.
  • --json: Emits a structured JSON summary to stdout upon completion (all other output is sent to stderr).
• Success Verification: Parse the JSON settlement envelope on stdout. Success is ok: true with commandId: "init"; details (e.g. scaffolded paths) live under result.

Handling refusals (ok: false)

--agent never implies --force. When a safety check trips, the CLI refuses and emits an errored settlement envelope to stdout:

{
  "ok": false,
  "commandId": "init",
  "error": {
    "code": "CLI.GIT_TREE_DIRTY",
    "severity": "error",
    "summary": "Git working tree is not clean.",
    "why": "Commit or stash your changes before running arkenv init.",
    "nextActions": [
      {
        "kind": "run-command",
        "label": "Re-run with --force to bypass git working tree check",
        "command": "arkenv init --force"
      }
    ]
  },
  "diagnostics": [],
  "nextActions": [
    {
      "kind": "run-command",
      "label": "Re-run with --force to bypass git working tree check",
      "command": "arkenv init --force"
    }
  ]
}

• error.code: a stable dotted identifier you can branch on (CLI.REQUIREMENTS_NOT_MET, CLI.GIT_TREE_DIRTY, CLI.NON_EMPTY_DIR, …). CLI.INTERNAL_ERROR means the CLI broke rather than refused — retrying with flags will not help.
• nextActions: remediation steps. A run-command action that includes --force means the refusal is bypassable; empty nextActions means it is not.

Escalation pattern: always run init --agent without --force first. If you get ok: false, inspect error.code and nextActions. Only re-run with --force (or the command from a run-command action) once you have deliberately decided the refusal is safe to bypass — do not add --force pre-emptively.