Environment Variables - Stars Components

@wolfstar/env-utilities loads layered dotenv files and provides strict parsers for application configuration.

Load with stars.config

With compatibility version 5, the default, stars loads your environment for you. When your project depends on @wolfstar/env-utilities, stars calls setup() as the very first import of the built entry, before plugin registrations and your own modules. Projects that build with tsdown or Vite no longer need to call setup() by hand. Pass setup() options through the env option of stars.config:

stars.config.ts

export default defineConfig({
	env: { prefix: 'BOT_', loader: 'varlock' }
});

env: false turns the automatic registration off. Projects that build with tsc, and JavaScript projects, set env: false and keep calling setup() themselves.
env: true, or any option, turns it on.
The registration stays off when experimental.enableNitro is set.

See Compatibility version for the other defaults of each version.

Load Dotenv Files

Outside the automatic stars.config registration, use the side-effect entry point when the default .env path is enough:

import '@wolfstar/env-utilities/setup';

For an explicit path or custom options, call setup:

import { setup } from '@wolfstar/env-utilities';

setup(new URL('../../.env', import.meta.url));

The loader applies environment-specific files with the most specific value first:

.env.development.local → .env.local → .env.development → .env
.env.test.local        → .env.test                    → .env

.env.local is intentionally skipped in the test environment.

Choose a Loader

setup() needs no extra package. It picks a loader in this order:

varlock: when the project has a varlock schema (src/.env.schema, .env.schema, or a varlock.loadPath in package.json).
dotenv: when the optional dotenv and dotenv-expand peer dependencies are installed.
node: otherwise. It parses files with Node.js’ util.parseEnv and requires Node.js 20.12 or newer.

Set the loader option or DOTENV_LOADER to choose one yourself. See Loaders for details.

How the CLI follows varlock

With future.compatibilityVersion 6, the stars CLI follows the runtime when it picks varlock by itself. The CLI treats the loader as varlock when all of these are true:

The project depends on @wolfstar/env-utilities.
The project has a varlock schema (src/.env.schema, .env.schema, or a varlock.loadPath in package.json).
varlock is installed.
stars.config sets neither env.path nor env.loader.

stars dev and stars doctor then read your variables through varlock load, the way the bot does, instead of the dotenv files. dev.url no longer takes its port from those dotenv files either. stars prepare, stars build, stars dev, and stars info print VARLOCK_LOADER_IMPLICIT when the CLI detects varlock but stars.config does not say so. Run stars doctor --fix to add env: { loader: 'varlock' } for you:

stars.config.ts

export default defineConfig({
	env: { loader: 'varlock' }
});

See stars doctor for the checks it runs.

Type Application Keys

Augment the package’s Env interface so parsers accept your keys:

import type { BooleanString, IntegerString } from '@wolfstar/env-utilities';

declare module '@wolfstar/env-utilities' {
	interface Env {
		ENABLE_TELEMETRY: BooleanString;
		HTTP_PORT: IntegerString;
		DISCORD_TOKEN: string;
	}
}

With a varlock schema, derive Env from the types varlock generates instead of declaring each key again:

import type { CoercedEnvSchema } from './env';
import type { EnvFromVarlock } from '@wolfstar/env-utilities/varlock';

declare module '@wolfstar/env-utilities' {
	interface Env extends EnvFromVarlock<CoercedEnvSchema> {}
}

You can also read varlock’s already-coerced values through the env export of @wolfstar/env-utilities/varlock. See With a varlock schema.

Parse Values

import { envParseBoolean, envParseInteger, envParseString } from '@wolfstar/env-utilities';

const telemetryEnabled = envParseBoolean('ENABLE_TELEMETRY', false);
const port = envParseInteger('HTTP_PORT', 3000);
const discordToken = envParseString('DISCORD_TOKEN');

Missing required keys throw ReferenceError. Invalid values throw TypeError. A provided default is returned as-is.

Configure the Loader Itself

You can set DOTENV_PATH, DOTENV_ENV, DOTENV_PREFIX, DOTENV_ENCODING, DOTENV_DEBUG, and DOTENV_LOADER before setup. Keep secrets outside source control and configure them through your deployment platform.

​Load with stars.config

​Load Dotenv Files

​Choose a Loader

​How the CLI follows varlock

​Type Application Keys

​Parse Values

​Configure the Loader Itself