Compatibility

envapt is ESM only and has two builds. The node build imports node:* modules, binds a FileSource when you import it, and reads .env files. The portable build doesn't import from node:, so it runs on Workers and in the browser, but it binds nothing until you call useSource.

Engine versionsCopy Anchor Link

InstallCopy Anchor Link

Quick Start has the command for npm, pnpm, yarn, and bun. Deno can install from either registry.

JSR doesn't have export conditions, and its @materwelon/envapt entry is the node build. It also doesn't have the config entry. For Workers or the browser, install from npm so the conditions can select the portable build.

Binding by runtimeCopy Anchor Link

The exports conditions in package.json select the build, so you import from envapt on every npm install.

Node build, binds automaticallyCopy Anchor Link

The node build's FileSource reads process.env plus the .env cascade, so the first read works with no setup.

Portable build, you bind a sourceCopy Anchor Link

Before the first read, bind a source built from the object or function the platform gives you. If you read before then, envapt throws NoSourceBound (307), whatever fileApiMode is.

Which condition selects which buildCopy Anchor Link

• The portable conditions come first in the exports map, so the first one your tool sets wins. If your bundler sets both browser and node, you get the portable build.
• Only the node build exports FileSource. Under a portable condition, importing FileSource from envapt fails.
• envapt/legacy follows the same conditions. envapt/config exists only in the node build, so use it on Node, Bun, and Deno.

File APIs and fileApiModeCopy Anchor Link

Envapter's envPaths, baseDir, envFileOptions, configureProfiles, and resetPaths read the filesystem (.env files on Node). On the portable build they have nothing to read. Envapter.fileApiMode takes a FileApiMode and sets what each call does there.

Keep 'warn' when one config module loads on both builds. With 'warn', setting envPaths does nothing on Workers and still loads files on Node. Choose 'throw' if you want a file API call on the portable build to stop the app. The error message says which API you called.

Envapter.fileApiMode = 'throw';

On the node build this line has no effect. If you bind a PortableSource on Node, the source has no files. Then setting envPaths or baseDir, or calling configureProfiles, throws FileApiUnsupported in either mode.

Module format and TypeScriptCopy Anchor Link

require('envapt') throws ERR_PACKAGE_PATH_NOT_EXPORTED, because the entries Node matches (node and default) are import-only. In a CommonJS project, load the package with await import('envapt') inside an async function. Load the config entry with node --import envapt/config.

export async function main(): Promise<number> {
    const { Converters, Envapter } = await import('envapt');
    return Envapter.getAs('PORT', Converters.Port, 3000);
}

main loads the package at call time, so a CommonJS file can reach envapt without require.

ERR_PACKAGE_PATH_NOT_EXPORTED from compiled codeCopy Anchor Link

With "module": "commonjs", tsc rewrites import('envapt') into require('envapt'). The compiled file then throws the error you were avoiding. "module": "node16" or "nodenext" keeps the import() call, so the same sample runs.

Cannot find module 'envapt' or its corresponding type declarationsCopy Anchor Link

TypeScript finds envapt through the exports map only under some module settings. These combinations were tested with TypeScript 6.0.3:

Use "type": "module" with module: "nodenext" if you run the compiled output on Node, since nodenext in a CommonJS package rejects a static import of envapt. Use moduleResolution: "bundler" if a bundler builds your app.

Decorators per runtimeCopy Anchor Link

@Envapt from envapt is a TC39 Stage 3 accessor decorator, and with TypeScript 5.0 or later it needs no compiler flag. The older form in envapt/legacy needs experimentalDecorators. The read methods like Envapter.getAs need neither. Decorators explains both forms.

{ "compilerOptions": { "experimentalDecorators": true } }

The Bun minimum is 1.3.11 because earlier versions emit Stage 3 decorators even with experimentalDecorators set, which makes a legacy @Envapt field throw a TypeError (bun#27575).