Environment

envapt detects which environment it's running in and exposes it through the isProduction / isStaging / isDevelopment / isTest helpers, which work on every runtime. On Node, Bun, and Deno it also loads the matching .env files for that environment.

Detecting the environment

The environment is resolved from the first of these keys with a non-missing value, falling back to development:

ENVIRONMENT → ENV → NODE_ENV → MODE → development

An empty value is skipped like an unset key. A whitespace-only value is skipped only under strict mode.

MODE is last because Vite-family browser builds expose import.meta.env.MODE but none of the others, so binding new PortableSource(import.meta.env) lets the same helpers work there. See Browser.

Read it as an enum, or through boolean helpers for the common checks.

Envapter.environment; // Environment
            
EnvironmentMethods.environment: Environment
Get the current application environment
Set the application environment. Accepts either Environment enum or string value.
@seehttps://envapt.materwelon.dev/docs/environment#detecting-the-environment@seehttps://envapt.materwelon.dev/docs/environment#detecting-the-environment
Envapter.isProduction; // boolean
Envapter.isStaging;
Envapter.isDevelopment;
Envapter.isTest;

Branching on the environment

Use the helpers where behavior should differ per environment.

const logLevel = Envapter.isProduction ? 'warn' : 'debug';
        
const logLevel: "warn" | "debug"

if (Envapter.isDevelopment) {
    // wire up dev-only tooling
}

Overriding detection

Set Envapter.environment to pin the environment explicitly, regardless of what the env vars say. It accepts the Environment enum or a string.

Envapter.environment = Environment.Staging;
Envapter.environment = 'production'; // strings work too

An explicit assignment also selects which .env files load on the next read, so set it before reading environment-specific values.

Per-environment .env files

For the detected (or overridden) environment (production, staging, development), envapt layers a dotenv-flow cascade, loading the first file that exists at each level, highest precedence first:

1. .env.${env}.local
2. .env.${env}
3. .env.local
4. .env

So in production it reads .env.production.local → .env.production → .env.local → .env. Values from higher-precedence files win; missing files are skipped.

Custom profiles

When your per-environment files live elsewhere, configureProfiles layers explicit paths on top of the cascade for the environments you name. Earlier paths in the array win. On the portable build these no-op by default, see Compatibility.

Envapter.configureProfiles({
    [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] },
    [Environment.Staging]: { paths: 'config/staging.env' }
});

Set useDefaults: false to load only the configured paths and skip the auto-cascade entirely.

Envapter.configureProfiles({
    [Environment.Production]: { paths: 'config/prod.env' },
    useDefaults: false
});

Envapter.resetProfiles(); // back to the pure cascade

To bypass environment-based selection altogether and load a fixed set of files, set Envapter.envPaths directly, covered in Configuration.