Skip to main content
Changes to @wolfstar/env-utilities. For the weekly summary across all packages, see the changelog overview.

​
2.3.1 (2026-10-06)

​
Updates

  • Dependencies — Updated all non-major dependencies. (#253)

​
2.3.0 (2026-10-04)

​
New features

  • EnvFromVarlock — Added EnvFromVarlock to derive Env from varlock’s generated CoercedEnvSchema, exported from the package root and from the new @wolfstar/env-utilities/varlock subpath. The README now states that envParseArray needs ArrayString keys, not plain string. EnvString also rejects optional number and boolean keys now, like required ones. (#260)
  • Node.js loader — Added a node loader that parses .env* files with Node.js’ own util.parseEnv (Node.js 20.12 or newer) and expands references like dotenv-expand. dotenv and dotenv-expand are now optional peer dependencies. When no loader is requested, dotenv is used if both packages are installed and the node loader if they are not, so a project that has them installed behaves as before and a varlock or new project installs nothing. Asking for loader: 'dotenv' without the packages throws an Error naming the missing one. EnvLoaderOptions no longer extends dotenv’s DotenvConfigOptions, and EnvSetupResult is now the package’s own EnvLoaderOutput. (#265)
  • Automatic varlock loader — The varlock loader is now picked automatically when varlock is installed and the project has a src/.env.schema, a .env.schema or a varlock.loadPath in package.json. An explicit path, the loader option and DOTENV_LOADER still win. Behaviour change: a project that already has a .env.schema and has varlock installed, but loaded its .env* files through dotenv, now loads through varlock after this release. Varlock reads the schema and its own .env* discovery, not src/.env* with NODE_ENV suffixes, so the values can differ: set loader: 'dotenv' (or DOTENV_LOADER=dotenv) to keep the previous behaviour. The loader is still experimental. (#262)
  • varlock load format — The experimental varlock loader now runs through varlock load --format json-full instead of varlock/auto-load. parsed now holds exactly the resolved keys, path and env map to --path and --env, and an invalid schema throws an Error with varlock’s summary instead of exiting the process. (#261)
  • Typed ENV export — Varlock’s typed ENV object is now exported as env from @wolfstar/env-utilities/varlock, filled by setup() when the varlock loader runs. (#263)

​
Updates

  • Automatic loader selection — With no loader requested, setup() picks varlock when varlock is installed and your project has a src/.env.schema, a .env.schema, or a varlock.loadPath in package.json. Otherwise it uses dotenv when dotenv and dotenv-expand are installed, and the node loader when they aren’t. An explicit path, the loader option, and DOTENV_LOADER still take precedence. #262 #265
  • Optional dotenv — dotenv and dotenv-expand are now optional peer dependencies. Requesting loader: 'dotenv' without them throws an Error naming the missing package. #265
  • varlock loader via the CLI — The experimental varlock loader now runs varlock load --format json-full instead of varlock/auto-load. parsed holds exactly the resolved keys, path and env map to --path and --env, and an invalid schema throws an Error with varlock’s summary instead of exiting the process. #261
  • Stricter EnvString — EnvString now rejects optional number and boolean keys, as it already did for required ones. Use ArrayString keys with envParseArray, not plain string. #260
  • Own option types — EnvLoaderOptions no longer extends dotenv’s DotenvConfigOptions, and EnvSetupResult is now the package’s own EnvLoaderOutput. #265
  • Dependencies — Updated third-party dependencies.

​
Migration

  • Projects with a .env.schema — If varlock is installed and your project has a .env.schema but you loaded .env* files through dotenv, setup() now loads them through varlock. varlock uses the schema and its own .env* discovery, not src/.env* with NODE_ENV suffixes, so values can differ. Set loader: 'dotenv' (or DOTENV_LOADER=dotenv) to keep the previous behaviour.
  • Explicit dotenv loader — If you set loader: 'dotenv' or DOTENV_LOADER=dotenv, install dotenv and dotenv-expand as dependencies of your project.
  • EnvLoaderOptions — Remove processEnv, quiet, override, fast, and DOTENV_KEY from your loader options. They were never forwarded and are no longer part of the type.

​
2.2.1

​
Bug fixes

  • Cross-file variable references — loadEnvFiles() used to expand every file right after loading it, so a specific file (e.g. .env.local) referencing a variable defined only in a more generic one (e.g. .env) silently resolved to an empty string. All files are now parsed first and expanded once, so references resolve regardless of load order. Precedence (specific over generic, src/.env* over root, existing process.env values kept) and the prefix filter (applied after expansion) are unchanged. (#226)
  • Circular references — Because a variable is now resolved from the merged result and no longer from the file that defined it, a specific file whose value expands to an empty string (e.g. K=${MISSING}) now ends up as '' in process.env instead of falling back to the value from a more generic file. Variables that are part of a circular reference spanning several variables now resolve to an empty string instead of hanging the process, including cycle shapes that previously terminated with a non-empty value (e.g. A=${B} / B=${A:-fallback}, or A=${B:+alt} / B=${A}). (#226)

​
Updates

  • Dependencies — Updated all non-major dependencies. (#227)

​
2.2.0 (2026-09-24)

​
New features

  • varlock support (experimental) — Load environment files with varlock instead of dotenv. Opt in with loader: 'varlock' or the DOTENV_LOADER environment variable. (#198)

​
2.1.1

​
Updates

  • Dependencies — Updated all non-major dependencies. (#178)

​
2.1.0

​
New features

  • Convention-first workflow — Compatibility version 4 is now the default, stars dev forces development mode, src/locales is copied and watched automatically, and environment files are discovered under both src/ and the project root. The interactive dev UI now supports t to open or close a public quick tunnel without configuring dev.tunnel. (#182)

​
Bug fixes

  • Logger fallback — Fixed a broken build caused by an incomplete removal of @wolfstar/logger. setup() now uses container.logger from @sapphire/pieces when available (populated by @wolfstar/http-framework), falling back to console.debug for standalone consumers, instead of the deprecated @wolfstar/logger package. (#182)

​
2.0.8

​
Updates

  • Type checker — Replaced tsc with golar as the type checker and bumped TypeScript to 7.0.2. typecheck scripts now run golar tsc instead of tsc directly. This is a dev-tooling-only change with no effect on published output. (#151)

​
2.0.7

​
Updates

  • Dependencies — Updated all non-major dependencies. (#126)

​
2.0.6

​
Updates

  • Dependencies — Updated all non-major dependencies. (#102)

​
2.0.5

​
Updates

  • Provenance attestation — Restored npm provenance attestation on publish for all packages. (#107)

​
2.0.4

​
Updates

  • Build tooling — Upgraded tsdown to 0.22.14 and migrated deps.skipNodeModulesBundle to deps.neverBundle. (#93)

​
2.0.3

​
Updates

  • Provenance attestation — Added provenance attestation to publishConfig for all packages. (#59)