ArkType

@arkenv/core is the ArkType engine: DSL strings, keywords such as number.port and string.host, and built-in string coercion.

For an overview of available engines, see Validators.

Installation

Install @arkenv/core and its peer dependency arktype:

npm install @arkenv/core arktype

pnpm add @arkenv/core arktype

yarn add @arkenv/core arktype

bun install @arkenv/core arktype

Define your schema

Declare environment variables in an env.ts file using ArkType string definitions or compiled type() objects:

import arkenv from "@arkenv/core";

export const env = arkenv({
  DATABASE_URL: "string",
  PORT: "number.port = 3000",
  DEBUG: "boolean = false",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
});

Import { env } from "./env" at application startup. If any required variables are missing or fail validation, ArkEnv throws an ArkEnvError with formatted issue details.

Automatic coercion

ArkEnv inspects the compiled ArkType schema's JSON Schema to automatically coerce incoming string values into numbers, booleans, and arrays before validation:

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    PORT: "number.port",
    DEBUG: "boolean",
    TAGS: "string[]",
  },
  {
    env: {
      PORT: "8080",
      DEBUG: "true",
      TAGS: "web, api",
    },
  },
);

env.PORT; // number
env.DEBUG; // boolean
env.TAGS; // string[]

To disable automatic string conversion and preserve raw strings for custom morphs, pass { coerce: false }. Learn more in Coercion.

Defaults and optionals

ArkType syntax supports inline default values and optional properties:

For specialized validators like string.host and number.port, see Keywords. To build complex custom schemas or morphs, see Defining types.

Next steps