/arkenv

name: arkenv
description: "Answer questions about ArkEnv and help implement environment variable validation. Use when developers: (1) Ask about environment variable validation or typesafety, (2) Want to setup ArkEnv in a project, (3) Need to define or update schemas using ArkType or Standard Schema, (4) Are integrating with Vite, Bun, or other runtimes. Triggers on: 'ArkEnv', 'env validation', 'typesafe env', 'createEnv', 'env.ts', '@arkenv/cli'."

ArkEnv

ArkEnv is a typesafe environment variable validator for modern JavaScript runtimes. It uses `ArkType` by default for schema definition but supports any `Standard Schema` validator (like `Zod` or `Valibot`).

Capabilities

Core usage

• Define typesafe schemas using `ArkType` notation or any `Standard Schema` validator.
• Implement complex types, arrays, and unions.
• Configure automatic coercion and default values.
• Follow best practices for schema organization.

Framework integration

• **Next.js**: Build-time/runtime validation and `process.env` type augmentation via `@arkenv/nextjs`. Supports automatic codegen (`env.gen.ts`) using the `withArkEnv` configuration wrapper in `next.config.ts`.
• **Vite**: Build-time validation and `import.meta.env` type augmentation via `@arkenv/vite-plugin`.
• **Bun**: Build-time/Runtime validation and `process.env` type augmentation via `@arkenv/bun-plugin`.
• **Node.js**: Standard `process.env` validation and coercion.

CLI (setup & DevOps)

• Initialize ArkEnv in new or existing projects using `pnpm dlx @arkenv/cli@latest init`.
• Scaffold schema files and detect framework-specific configurations (`Next.js`, `Vite`, `Bun`, etc.).
• Support layout selection (`--strict` for 3-file split vs `--simple` for a single file).
• Support option to skip codegen (`--no-codegen`).
• Automatically configure `tsconfig.json` and environment types for optimal typesafety.

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/cli@latest 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 output to verify `status: "success"` and retrieve details like the scaffolded file path.

Handling refusals (`status: "error"`)

`--agent` **never** implies `--force`. When a safety check trips, the CLI refuses and emits a machine-actionable JSON payload to `stdout`:

{
  "status": "error",
  "code": "GIT_TREE_DIRTY",
  "message": "Git working tree is not clean.",
  "retryWith": ["--force"]
}

• **`code`**: a stable identifier you can branch on. Refusal codes: `REQUIREMENTS_NOT_MET`, `GIT_TREE_DIRTY`, `NON_EMPTY_DIR`. A `code` of `INTERNAL` means the CLI _broke_ rather than _refused_ - retrying with flags will not help.
• **`retryWith`**: the flag(s) that would bypass the check (e.g. `["--force"]`). Empty (`[]`) means the refusal is not bypassable.

**Escalation pattern**: always run `init --agent` **without** `--force` first. If you get `status: "error"`, inspect `code` and `retryWith`. Only re-run with the flag(s) from `retryWith` (e.g. append `--force`) once you have deliberately decided the refusal is safe to bypass - do not add `--force` pre-emptively.

Operational logic

1. **Detection**:

• Look for `env.ts` (simple layout) or an `env/` directory containing split files: `env/client.ts`, `env/server.ts`, and `env/internal/shared.ts` (strict layout).
• Check for framework config files (`next.config.ts`, `next.config.js`, `vite.config.ts`, `bunfig.toml`, `package.json` scripts) to recommend appropriate plugins.

2. **Setup**:

• If ArkEnv is not present or a fresh setup is requested, trigger the **Setup Workflow**.
• Prefer using the CLI for initialization: `pnpm dlx @arkenv/cli@latest init`.
• If the CLI cannot be used or fails, fall back to manual configuration.

Setup workflow

When setting up ArkEnv, follow these steps:

1. **Initialize**: Run `pnpm dlx @arkenv/cli@latest init --agent` (optionally appending `--strict` or `--simple` based on layout preference). This will detect the environment, install dependencies, and scaffold schemas. 2. **Review & Refine Schemas**:

• **Simple Layout**: Inspect and refine the generated `env.ts`. Ensure it captures the required environment variables.
• **Strict Layout**: Inspect and refine the generated files under the `env/` directory: `client.ts` (client-only variables), `server.ts` (server-only variables), and `internal/shared.ts` (variables shared between client and server).
• Refine types (e.g., change `string` to `number.port` or specific union types).

3. **Manual Plugin Configuration**:

• The CLI installs plugins but might not update config files.
• **Next.js**: Wrap `next.config.ts` (or `next.config.js`) using the `withArkEnv` configuration helper from `@arkenv/nextjs/config`. (Skip if scaffolded with `--no-codegen`).
• **Vite**: Update `vite.config.ts` to import and include the `@arkenv/vite-plugin` plugin.
• **Bun**: Configure `bunfig.toml` or add the plugin to the runtime if necessary.

4. **Typesafety & Augmentation**:

• **Next.js (Codegen)**: Import `createEnv` from `./generated/env.gen` instead of core `@arkenv/nextjs`. The codegen file automatically handles the runtime mapping and type definitions.
• **Vite**: Add type augmentation to `src/vite-env.d.ts` or a new `env.d.ts`.

     interface ImportMetaEnv extends import("@arkenv/vite-plugin").ImportMetaEnvAugmented<typeof import("./env").Env> {}

• **Bun**: Create a `