> ## Documentation Index
> Fetch the complete documentation index at: https://stars-components.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Load and parse typed environment variables with @wolfstar/env-utilities.

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

## Load Dotenv Files

Use the side-effect entry point when the default `.env` path is enough:

```typescript theme={"system"}
import '@wolfstar/env-utilities/setup';
```

For an explicit path or custom options, call `setup`:

```typescript theme={"system"}
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:

```text theme={"system"}
.env.development.local → .env.local → .env.development → .env
.env.test.local        → .env.test                    → .env
```

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

## Type Application Keys

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

```typescript theme={"system"}
import type { BooleanString, IntegerString } from '@wolfstar/env-utilities';

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

## Parse Values

```typescript theme={"system"}
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`, and `DOTENV_DEBUG` before setup. Keep secrets
outside source control and configure them through your deployment platform.