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

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

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 (
```
Vite
```
,
```
Bun
```
, etc.).
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.

Operational Logic

Detection:
- Look for
```
env.ts
```
  or
```
arkenv
```
  imports to understand existing schema.
- Check for framework config files (
```
vite.config.ts
```
  ,
```
bunfig.toml
```
  ,
```
package.json
```
  scripts) to recommend appropriate plugins.
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:

Initialize: Run
```
pnpm dlx @arkenv/cli@latest init --agent
```
. This will attempt to detect the environment, install dependencies, and scaffold a base
```
env.ts
```
.
Review & Refine
env.ts
:
- Inspect the generated
```
env.ts
```
  . Ensure it captures the required environment variables.
- Refine types (e.g., change
```
string
```
  to
```
number.port
```
  or specific union types).
Manual Plugin Configuration:
- The CLI installs plugins but might not update config files.
- Vite: Update
```
vite.config.ts
```
  to import and include the
```
arkenv
```
  plugin.
- Bun: Configure
```
bunfig.toml
```
  or add the plugin to the runtime if necessary.

Typesafety & Augmentation:

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

bun-env.d.ts

file (or update an existing one) with the following pattern:

/// <reference types="bun-types" />
type ProcessEnvAugmented = import("@arkenv/bun-plugin").ProcessEnvAugmented<typeof import("./src/env").default>;
declare namespace NodeJS {
  interface ProcessEnv extends ProcessEnvAugmented {}
}

Ensure
```
tsconfig.json
```
has
```
strict: true
```
(the CLI tries to do this, but verify).

Usage Update: Scan the codebase for existing environment variable usage (
```
process.env
```
or
```
import.meta.env
```
) and ensure they are now typesafe via the augmentations.
Validation: Run
```
pnpm check
```
(or equivalent) or a build to confirm everything is typesafe and valid.

Core Concepts

Defining a Schema

The best practice is to export a schema definition using

type

import { type } from 'arkenv';

export const Env = type({
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
  VITE_API_URL: "string",
  PORT: "number.port = 3000"
});

Usage: Node.js (Standard)

In Node.js, you validate the environment at runtime and export the result.

import arkenv from 'arkenv';
import { Env } from './env';

export const env = arkenv(Env);

// Usage
const port = env.PORT; // typed as number

Usage: Vite (Frontend)

Vite requires build-time injection. Use the plugin in

vite.config.ts

and augment

ImportMetaEnv

// vite.config.ts
import arkenv from '@arkenv/vite-plugin';
import { Env } from './env';

export default defineConfig({
  plugins: [arkenv(Env)]
});

// src/vite-env.d.ts
import type { ImportMetaEnvAugmented } from "@arkenv/vite-plugin";
import type { Env } from "../env";

interface ImportMetaEnv extends ImportMetaEnvAugmented<typeof Env> {}

Usage: Bun

Bun can use either runtime validation or a plugin for type augmentation.

// src/env.d.ts
import type { ProcessEnvAugmented } from "@arkenv/bun-plugin";
import type { Env } from "./env";

declare global {
  namespace NodeJS {
    interface ProcessEnv extends ProcessEnvAugmented<typeof Env> {}
  }
}

CLI Commands

init

Set up ArkEnv in your project. It detects your framework and configures the appropriate plugin and type augmentations.

bash

pnpm dlx @arkenv/cli@latest init

Best Practices

Prefer Native Primitives: To leverage the full power of ArkEnv plugins, you should access environment variables through the runtime's native primitives.
- Vite: Use
```
import.meta.env
```
  .
- Bun: Use
```
process.env
```
  .
- This ensures that build-time validation, static replacement (Vite), and runtime optimizations (Bun) work as intended while remaining fully typesafe via type augmentation.
Avoid
import { env }
in Plugin-managed Projects: In projects using
```
@arkenv/vite-plugin
```
or
```
@arkenv/bun-plugin
```
, you should generally avoid importing a runtime-validated
```
env
```
object. Using native primitives is the "cleanest" way to get typesafety and ensures consistency with framework-specific behavior.
Use Type Augmentation: This is the recommended way to make
```
import.meta.env
```
or
```
process.env
```
typesafe. It connects your schema definition to the native primitives without adding runtime overhead to your application logic.
Re-use Schema: Define your schema once and use it for both the plugin (build-time/config) and runtime validation if needed.
Coercion: ArkEnv automatically coerces strings from
```
.env
```
files (e.g.,
```
"3000"
```
becomes
```
3000
```
).

arkenv

NPX Install

Tags

SKILL.md Content