Environment Vars

Get environment-specific values at runtime without rebuilding your application.

When to Use This

Use @availity/env-var when:

You need different config values per environment. API base URLs, feature flags, client IDs, or any value that changes between test/QA/prod but shouldn't require a separate build.
You are building an immutable artifact. A single JavaScript bundle that detects its environment at runtime via window.location.hostname and selects the appropriate value.
You need the current environment name. Determine whether you are running in 'local', 'test', 'qa', or 'prod' for conditional logic.

Installation

NPM

npm install @availity/env-var

Yarn

yarn add @availity/env-var

Supported URL Formats

The package detects the environment from window.location using the subdomain of *.availity.com portal URLs:

Subdomain	Category	Specific Slug
`localhost`, `127.0.0.1`	`local`	`local`
`apps`, `essentials`	`prod`	`prod`
`test-apps`, `test-essentials`	`test`	`test`
`t01-apps`, `t14-apps`, …	`test`	`t01`, `t14`, …
`qa-apps`, `qa-essentials`	`qa`	`qa`
`qap-apps`, `q01-apps`, …	`qa`	`qap`, `q01`, …

Any URL that does not match a known pattern is treated as local.

API Reference

envVar (default export)

This function accepts an object, and will return a value based on what environment you are in. You can also pass in a window override as well as a default value.

import envVar from '@availity/env-var';

const myEnvVal = envVar(values, windowOverride, defaultValue);

export default myEnvVal;

Required args

values: An object with keys which match the name of the potential environments. The value for the current environment will be returned

Optional args

windowOverride: String, Window Object, or null which can be used to override the window which is used to determine the current hostname (which is used to determine the current environment)
- When a string, it will be taken as a fully qualified URL and the hostname will be parsed from it.
- When a Window Object, the location.hostname will be used.
- When null (or when window is not available, e.g. SSR/Node), falls back to local.
defaultValue: The value returned when one does not exist for the specified environment. If no default is provided, then the function will use the value specified for local

Example

import envVar from '@availity/env-var';

/*
    myEnvVal will be different depending on the environment the code runs in
        prod: myEnvVal will be '123'
        qa: myEnvVal will be '234'
        test: myEnvVal will be '345' (defaults to local if env is not found)
*/
const myEnvVal = envVar({ prod: '123', qa: '234', local: '345' });

export default myEnvVal;

setEnvironments

Set the potential environments and the tests used to determine which environment the code is currently being executed in.

import { setEnvironments } from '@availity/env-var';

setEnvironments(environments, override);

Required args

environments: An object with keys which match the name of the potential environments and the values are the tests which are ran to determine if the environment is the current one.

These tests can be

String: A string will be used to check an exact match.
Regular Expression: A regex will be tested with the domain.
Function: The function will be called and the result should be a boolean indicating if the environment is the current environment.
Array: An array containing any of the above types.

Optional args

override: Boolean, when true possibleEnvironments will replace the existing environments instead of merging.

Example

import { setEnvironments } from '@availity/env-var';

setEnvironments({
  local: ['127.0.0.1', 'localhost'],
  test: [/^t(?:(?:\d\d)|(?:est))-(apps|essentials)$/],
  qa: [/^q(?:(?:\d\d)|(?:ap?))-(apps|essentials)$/],
  prod: [/^(apps|essentials)$/],
  myEnv: ['custom-stuff-here'],
});

getSpecificEnv

Get the specific current environment, without rolling up to the general environment. Whereas envVar treats the t01 environment as test, for example, getSpecificEnv returns 't01' for the t01 environment.

import { getSpecificEnv } from '@availity/env-var';

const specificEnv = getSpecificEnv(windowOverride);

Required args

None

Optional args

windowOverride: String or Window Object which can be used to override the window which is used to determine the current hostname (which is used to determine the current environment)
- When a string, it will be taken as a fully qualified URL and the hostname will be parsed from it.
- When a Window Object, the location hostname will be used.

Example

import { getSpecificEnv } from '@availity/env-var';

/*
depending on the environment this code runs in, specificEnv would be something different,
like 't01' or 'qap' or 'prod'
*/
const specificEnv = getSpecificEnv();

setSpecificEnvironments

Set the tests that will be used to determine the specific environment the code is currently being executed in.

import { setSpecificEnvironments } from '@availity/env-var';

setSpecificEnvironments(environments, override);

Required args

environments: An array of objects with the following keys:
- regex: the regular expression to match against the current subdomain
- fn: the function to run to return the name of the environment as a string

The code will iterate through the objects, matching the subdomain against the regex. If the regex matches, the code calls the corresponding fn, passing an object containing the match (capturing groups), subdomain, and pathname. The iteration stops when it receives a non-empty answer from a function or when it reaches the end, in which case it returns 'local'.

Optional args

override: Boolean, when true possibleEnvironments will replace the existing environments instead of merging.

Example

import { setSpecificEnvironments } from '@availity/env-var';

setSpecificEnvironments([
  {
    regex: /^(?:(.*)-)?(essentials)$/,
    fn: (options) => options.match[1] || 'prod',
  },
]);

getCurrentEnv

Get the general environment name (e.g., 'local', 'test', 'qa', 'prod') for the current hostname.

import { getCurrentEnv } from '@availity/env-var';

const env = getCurrentEnv();
// => 'prod'

Optional args

windowOverride: String or Window Object which can be used to override the window used to determine the hostname.

Example

import { getCurrentEnv } from '@availity/env-var';

// Use a custom URL for testing
const env = getCurrentEnv(
  'https://test-essentials.availity.com/static/web/onb/onboarding-ui-apps/navigation/#/'
);
// => 'test'

getEnvironmentInfo

Returns both the broad environment category and the specific slug in a single call. Useful when you need both values — avoids parsing the location twice.

import { getEnvironmentInfo } from '@availity/env-var';

const { env, specificEnv } = getEnvironmentInfo();
// => { env: 'test', specificEnv: 't01' }

Optional args

windowOverride: String, Window Object, or null. Same semantics as getCurrentEnv.

Example

import { getEnvironmentInfo } from '@availity/env-var';

const { env, specificEnv } = getEnvironmentInfo(
  'https://t01-essentials.availity.com'
);
// => { env: 'test', specificEnv: 't01' }

isProd / isQa / isTest / isLocal

Convenience boolean helpers. Equivalent to getCurrentEnv() === 'env' but more readable and easier to autocomplete.

import { isProd, isQa, isTest, isLocal } from '@availity/env-var';

Each accepts an optional windowOverride (String, Window Object, or null) with the same semantics as getCurrentEnv.

Example

import { isProd, isLocal } from '@availity/env-var';

if (isProd()) {
  // only runs in prod
}

if (isLocal()) {
  // runs on localhost, 127.0.0.1, or any unrecognised host
}

// With a URL string (useful in tests or SSR)
isProd('https://essentials.availity.com'); // => true
isTest('https://t01-essentials.availity.com'); // => true

Note: isLocal returns true for both localhost/127.0.0.1 and any unrecognised host — the same fallback behaviour as envVar.

resetEnvironments / resetSpecificEnvironments

Restore the built-in environment definitions after a setEnvironments or setSpecificEnvironments call. Primarily useful in tests to prevent state from bleeding between test cases.

import {
  resetEnvironments,
  resetSpecificEnvironments,
} from '@availity/env-var';

Example

import {
  setEnvironments,
  resetEnvironments,
  resetSpecificEnvironments,
} from '@availity/env-var';

// In a test file
afterEach(() => {
  resetEnvironments(); // restore built-in environments
  resetSpecificEnvironments(); // restore built-in specific environments
});

test('custom environment', () => {
  setEnvironments({ staging: /^stg-apps$/ });
  // ... assertions ...
}); // reset called after each test — no state bleed

SSR / Node Usage

All functions default to null when window is not available (e.g. server-side rendering with Vite SSR, Next.js, or any Node environment). A null window is treated as an unrecognised host — getCurrentEnv returns '' and envVar falls back to varObj.local.

import envVar, { getCurrentEnv } from '@availity/env-var';

// Safe in Node — no window reference errors
const env = getCurrentEnv(); // => '' (falls back to local in envVar)

const apiUrl = envVar({
  prod: 'https://api.availity.com',
  qa: 'https://qa-api.availity.com',
  local: 'http://localhost:3000',
}); // => 'http://localhost:3000' in SSR/Node

// Pass a URL string explicitly when the target environment is known at render time:
const ssrEnv = getCurrentEnv('https://essentials.availity.com'); // => 'prod'

When to Use This​

Installation​

NPM​

Yarn​

Supported URL Formats​

API Reference​

envVar (default export)​

Required args​

Optional args​

Example​

setEnvironments​

Required args​

Optional args​

Example​

getSpecificEnv​

Required args​

Optional args​

Example​

setSpecificEnvironments​

Required args​

Optional args​

Example​

getCurrentEnv​

Optional args​

Example​

getEnvironmentInfo​

Optional args​

Example​

isProd / isQa / isTest / isLocal​

Example​

resetEnvironments / resetSpecificEnvironments​

Example​

SSR / Node Usage​

When to Use This

Installation

NPM

Yarn

Supported URL Formats

API Reference

envVar (default export)

Required args

Optional args

Example

setEnvironments

Required args

Optional args

Example

getSpecificEnv

Required args

Optional args

Example

setSpecificEnvironments

Required args

Optional args

Example

getCurrentEnv

Optional args

Example

getEnvironmentInfo

Optional args

Example

isProd / isQa / isTest / isLocal

Example

resetEnvironments / resetSpecificEnvironments

Example

SSR / Node Usage