@dotenvx/providers

@dotenvx/providers

npm install @dotenvx/providers

const { provider } = require('@dotenvx/providers')
const { parse, parseSync } = require('@dotenvx/primitives')

const keys = provider()

// Async
const result = await parse(source, { provider: keys.get })

// Sync
const resultSync = parseSync(source, { provider: keys.getSync })

Looks up private keys in this order, stopping at the first match:

• .env.keys
• macOS Keychain
• Windows Credential Manager
• Linux Secret Service
• Dotenvx Armor (including enclave decryption)
• 1Password
• Bitwarden

providerOrder exports the same order for consumers with custom provider adapters. The platform's native store occupies one step between .env.keys and Armor.

Optional onLookup(name) and onLookupEnd(name) callbacks let consumers show progress without owning the lookup order. They run around each attempted lookup in both get and getSync; onLookupEnd also runs when a lookup throws. These synchronous callbacks should not throw.

Armor errors fall through to password managers. If none finds the key, the original Armor error is thrown. Other provider errors propagate immediately. An optional onArmorError(error) callback receives an unresolved Armor error instead of throwing it, allowing consumers with an additional interactive fallback to try it before reporting the error.

isNetworkError(error) classifies transport failures, including nested causes and aggregate errors. Armor normalizes those failures to ARMOR_UNREACHABLE with message, help, and messageWithHelp, preserved by synchronous workers. Consumers display these messages and choose whether to continue parsing without a resolved key; they do not need their own transport error-code lists.

Approval prompts

Armor prints an approval URL to stderr before polling when no onApprovalRequired({ approvalUri, code }) callback is supplied. Synchronous lookups print from their worker directly, so the prompt stays visible while the calling thread is blocked. Callbacks are only supported by asynchronous lookups.

An async consumer can customize presentation with onApprovalRequired, or call the exported approvalRequired(info) inside its callback to use the default message (for example, after stopping a spinner).