Migrating from a getEnv helper

ArkEnv is designed to replace handwritten environment variable helpers with zero boilerplate. ArkEnv provides declarative parsing, automatic coercion, and framework boundaries using the TypeScript validator you already know.

A lightweight presence check is often the first thing teams write to validate process.env. It installs zero dependencies and types keys as string. But as soon as an application introduces booleans, port numbers, or browser bundles, presence-only checks fail quietly.

The DIY helper

Most handwritten helpers check whether required keys exist in process.env:

export function getEnv() {
  const { PORT, DEBUG, DATABASE_URL, STRIPE_SECRET } = process.env;

  if (
    PORT === undefined ||
    DEBUG === undefined ||
    DATABASE_URL === undefined ||
    STRIPE_SECRET === undefined
  ) {
    throw new Error("Missing required environment variables");
  }

  return { PORT, DEBUG, DATABASE_URL, STRIPE_SECRET };
}

This helper works when all variables are required strings. The breakdown happens when values need coercion or client/server separation.

Failure classes comparison

The table below contrasts how a presence helper behaves compared to ArkEnv:

Forensic breakdown

function getEnv() {
  const debug = process.env.DEBUG;
  if (debug === undefined) {
    throw new Error("missing DEBUG");
  }
  return { debug };
}

const { debug } = getEnv();

if (debug) {
  // always runs when DEBUG is set — including DEBUG=false
}

const { port } = getEnv();
// port: string

listen(port);
port + 1; // "30001"
port > 1024; // lexicographic, not numeric

DATABASE_URL=

export const env = getEnv();
// env.STRIPE_SECRET accessed in a client component

Graduating to ArkEnv

Replace the helper with a single declarative schema in ./env.ts:

import arkenv from "@arkenv/core";

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

env.PORT; // number
env.DEBUG; // boolean

To scaffold ArkEnv in your project:

npx arkenv init

pnpm dlx arkenv init

yarn dlx arkenv init

bunx arkenv init

Next steps