# envapt

> Read config as real typed values from any source, process.env, a Cloudflare Workers binding, a browser bundle, or any object you bind. Zero runtime dependencies and zod/valibot/arktype validation. Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.

- Import the readers and decorators from `envapt` on every runtime. The package's export conditions pick the Node build or the portable build. The legacy decorators for `experimentalDecorators` come from `envapt/legacy`.
- On Node, Bun, and Deno, envapt reads `process.env` and the `.env` files on import. On Cloudflare Workers, in the browser, and on other edge runtimes, call `Envapter.useSource` before the first read.
- Method names and import paths changed between majors. Read the page for an API before you write code against it. The migration pages list what changed in each major.
- Each docs page has a markdown copy, and https://envapt.materwelon.dev/llms.txt links every one. A request for a docs page with `Accept: text/markdown` also returns the markdown.
- The steps for writing envapt code are in the agent skill at https://envapt.materwelon.dev/.well-known/agent-skills/envapt/SKILL.md.

## Docs

- Guide
  - [Introduction](https://envapt.materwelon.dev/llms/docs/): Read environment config as typed values with a fallback, in place of process.env parsed by hand, on Node, Bun, Deno, Workers, and the browser.
  - [Quick Start](https://envapt.materwelon.dev/llms/docs/quick-start/): Install envapt and read typed config on Node, Workers, or the browser, binding the platform's env object first outside Node, Bun, and Deno.
  - [Structuring your config](https://envapt.materwelon.dev/llms/docs/app-config/): Read your app's variables once, in one typed config module that throws at boot on a bad deploy, then import the values from every other file.

  - **Reading config**
  - [Reading values](https://envapt.materwelon.dev/llms/docs/envapter/): Read one environment variable as a string or through a converter, with a fallback, and see what each reader returns for a bad value.
  - [Converters](https://envapt.materwelon.dev/llms/docs/converters/): Turn a raw environment string into a number, URL, duration, list, or any type you need, with a built-in token or your own function.
  - [Validating with a schema](https://envapt.materwelon.dev/llms/docs/standard-schema/): Check an environment value against a zod, valibot, or arktype schema and get the schema's output type back, with the failed rule in the error's issues.
  - [Required values](https://envapt.materwelon.dev/llms/docs/required-values/): Stop the app at boot when a variable is missing or malformed, and see every missing key, or every malformed key, in one error.
  - [Templates](https://envapt.materwelon.dev/llms/docs/templates/): Build one environment variable from others by referencing them inside its value, and assemble strings from several keys with the resolve() tagged template.
  - [Decorators](https://envapt.materwelon.dev/llms/docs/decorators/): Declare typed config as class fields with @Envapt, using accessor fields by default or the legacy decorators from envapt/legacy.

  - **Loading config**
  - [Sources](https://envapt.materwelon.dev/llms/docs/sources/): Pass your platform's config object to envapt with useSource so typed reads work on Workers, the browser, and edge runtimes.
  - [Environment](https://envapt.materwelon.dev/llms/docs/environment/): Read the environment envapt detects from ENVIRONMENT, ENV, NODE_ENV, or MODE, and pin it yourself when a script or a test needs a fixed one.
  - [.env files on Node](https://envapt.materwelon.dev/llms/docs/env-files/): Get per-environment .env files loading in the right order on Node, Bun, and Deno, and replace dotenv's config import with envapt's.
  - [.env file syntax](https://envapt.materwelon.dev/llms/docs/env-file-syntax/): Write .env values with quotes, # characters, or multi-line text so envapt parses each one the way you meant it.
  - [Secret stores](https://envapt.materwelon.dev/llms/docs/secret-stores/): Read secrets from your secrets manager as typed values, either through a wrapper CLI or by fetching them at boot and binding them next to your .env files.
  - [Testing](https://envapt.materwelon.dev/llms/docs/testing/): Give each vitest test its own config instead of your machine's, then restore the real source after each test.

  - **Runtimes**
  - [Compatibility](https://envapt.materwelon.dev/llms/docs/compatibility/): Look up the Node, Bun, and Deno versions envapt needs, which build your runtime loads, and the TypeScript settings that let you import it.
  - [Cloudflare Workers](https://envapt.materwelon.dev/llms/docs/workers/): Read typed config from a Worker's vars and secrets by binding the Cloudflare env object once, in a config module that runs when the Worker loads.
  - [Edge runtimes](https://envapt.materwelon.dev/llms/docs/edge-runtimes/): Pass envapt the config that Vercel Edge, Fastly Compute, or Expo gives you, then read typed values with the same API you use on Node.
  - [Browser](https://envapt.materwelon.dev/llms/docs/browser/): Bind Vite's import.meta.env to envapt once, then read each VITE_ string in your bundle as the URL or boolean your app code expects.

  - **Frameworks**
  - [Next.js](https://envapt.materwelon.dev/llms/docs/nextjs/): Read typed config in a Next.js app from server code, client components, and edge routes, and catch a missing variable at build time or at server start.
  - [SvelteKit, Astro, and Nuxt](https://envapt.materwelon.dev/llms/docs/other-frameworks/): Run typed envapt config in a SvelteKit, Astro, or Nuxt server on Node, with the start command and startup checks each framework needs.
  - [Building on envapt](https://envapt.materwelon.dev/llms/docs/building-on-envapt/): Read config from a library, framework, or CLI that depends on envapt, so the source, environment, and .env files the app sets up reach your reads.

  - **Reference**
  - [Errors and debugging](https://envapt.materwelon.dev/llms/docs/errors/): Find what an EnvaptError code means, and turn on debug logging to see why a read returned your fallback.
  - Migrations
    - [Migrations](https://envapt.materwelon.dev/llms/docs/migrations/): Find the breaking changes in each envapt major release from v5 to v9, and the edits each one asks of your code.
    - [Migration (v8 to v9)](https://envapt.materwelon.dev/llms/docs/migration-v8-to-v9/): Move a v8 app to envapt v9, which requires Node 22.23.3 and ESM, and find the behavior changes that still compile.
    - [Migration (v7 to v8)](https://envapt.materwelon.dev/llms/docs/migration-v7-to-v8/): Upgrade from envapt v7 to v8, where the source classes get shorter names and one envapt import replaces the workerd and browser subpaths.
    - [Migration (v6 to v7)](https://envapt.materwelon.dev/llms/docs/migration-v6-to-v7/): Upgrade from envapt v6 to v7, where the default decorators become TC39 Stage 3 accessors and the legacy ones move to envapt/legacy.
    - [Migration (v5 to v6)](https://envapt.materwelon.dev/llms/docs/migration-v5-to-v6/): Upgrade from envapt v5 to v6, where the positional decorator form is removed and NODE_ENV=test resolves to the test environment.
    - [Migration (v4 to v5)](https://envapt.materwelon.dev/llms/docs/migration-v4-to-v5/): Upgrade from envapt v4 to v5, where Converters.array() and envFileOptions replace the old names and per-environment .env files load on their own.
- API reference
  - [API reference](https://envapt.materwelon.dev/llms/docs/api/): Every export of envapt and envapt/legacy, with signatures, parameters, and return types generated from the library's type definitions.
  - envapt
    - [envapt](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/)
    - Classes
      - [Envapter](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/classes/Envapter/)
      - [EnvaptError](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/classes/EnvaptError/)
      - [FileSource](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/classes/FileSource/)
      - [PortableSource](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/classes/PortableSource/)
    - Functions
      - [Envapt](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/functions/Envapt/)
      - [merge](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/functions/merge/)
    - Interfaces
      - [EnvaptIssue](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/interfaces/EnvaptIssue/)
      - [EnvFileOptions](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/interfaces/EnvFileOptions/)
      - [EnvProfile](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/interfaces/EnvProfile/)
      - [StandardSchemaV1](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/interfaces/StandardSchemaV1/)
    - Namespaces
      - StandardSchemaV1
        - [StandardSchemaV1](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/)
        - Interfaces
          - [FailureResult](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/FailureResult/)
          - [Issue](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/Issue/)
          - [PathSegment](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/PathSegment/)
          - [Props](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/Props/)
          - [SuccessResult](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/SuccessResult/)
          - [Types](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/interfaces/Types/)
        - Type aliases
          - [InferInput](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/type-aliases/InferInput/)
          - [InferOutput](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/type-aliases/InferOutput/)
          - [Result](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/namespaces/StandardSchemaV1/type-aliases/Result/)
    - Type aliases
      - [ConverterFunction](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/ConverterFunction/)
      - [DebugLevel](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/DebugLevel/)
      - [EnvaptErrorCodes](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/EnvaptErrorCodes/)
      - [Environment](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/Environment/)
      - [FileApiMode](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/FileApiMode/)
      - [JsonValue](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/JsonValue/)
      - [ProfilesConfig](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/ProfilesConfig/)
      - [Source](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/Source/)
      - [TimeFallback](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/type-aliases/TimeFallback/)
    - Variables
      - [Converters](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/variables/Converters/)
      - [EnvaptErrorCodes](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/variables/EnvaptErrorCodes/)
      - [ENVIRONMENT_KEYS](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/variables/ENVIRONMENT_KEYS/)
      - [Environment](https://envapt.materwelon.dev/llms/docs/api/reference/envapt/variables/Environment/)
  - legacy
    - [legacy](https://envapt.materwelon.dev/llms/docs/api/reference/legacy/)
    - Functions
      - [Envapt](https://envapt.materwelon.dev/llms/docs/api/reference/legacy/functions/Envapt/)
    - Type aliases
      - [EnvaptFieldDecorator](https://envapt.materwelon.dev/llms/docs/api/reference/legacy/type-aliases/EnvaptFieldDecorator/)

## Blog

- [How seedcord uses envapt](https://envapt.materwelon.dev/blog/seedcord-and-envapt/): seedcord, my Discord bot framework, reads its config through envapt. Here's what that saves it on Node, Workers, and the CLI, and the bugs it took to get there.
- [What changed in envapt v6, v7, and v8](https://envapt.materwelon.dev/blog/whats-new-v6-to-v8/): Three majors of envapt, and the dogfooding behind each one, from removing a decorator footgun to one universal import that reads config the same on Node and the edge.
- [Reading typed config in TypeScript](https://envapt.materwelon.dev/blog/reading-typed-env/): Read config from any source as numbers, URLs, durations, and schema-validated values in TypeScript, with fallbacks that narrow the type and any Standard Schema validator you already use.