> ## 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.

# @wolfstar/env-utilities

> Load, type, and parse environment variables safely.

<CodeGroup>
  ```bash npm theme={"system"}
  npm install @wolfstar/env-utilities
  ```

  ```bash pnpm theme={"system"}
  pnpm add @wolfstar/env-utilities
  ```

  ```bash yarn theme={"system"}
  yarn add @wolfstar/env-utilities
  ```

  ```bash bun theme={"system"}
  bun add @wolfstar/env-utilities
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="npm" icon="npm" horizontal href="https://npmx.dev/package/@wolfstar/env-utilities" />

  <Card title="Source" icon="github" horizontal href="https://github.com/wolfstar-project/stars-components/tree/main/packages/env-utilities" />
</CardGroup>

## Description

Functional utilities for reading and parsing environmental variables, based on [Wolfstar](https://wolfstar.rocks)'s internal tools.

## Usage

### Setup

To setup `@wolfstar/env-utilities`, you use the `setup` function exported by the package:

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

// Finds src/.env* and .env* from the current project automatically.
setup();
```

Alternatively, if you do not need to provide any custom options you can import it as a side effect:

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

You can also pass a `string` or if you want to define other options, you may use `EnvSetupOptions`. Optionally, you may configure dotenv via environment variables:

* `DOTENV_DEBUG`: configures `EnvSetupOptions.debug`. If enabled, the library will log to help debug why certain keys or values are not being set as expected.
* `DOTENV_ENCODING`: configures `EnvSetupOptions.encoding`. If set, it will specify the encoding of the files containing the environment variables
* `DOTENV_ENV`: configures `EnvSetupOptions.env`. If set, it will specify a custom environment if `NODE_ENV` is not sufficient.
* `DOTENV_PATH`: configures `EnvSetupOptions.path`. If set, it will specify a custom path to the file containing environment variables, useful for when they are located elsewhere.
* `DOTENV_PREFIX`: configures `EnvSetupOptions.prefix`. If set, it will specify a required prefix for dotenv variables (e.g. `APP_`).

### What `.env` files can be used?

Every file below is searched first under `src/`, then at the project root. An explicit `path` or `DOTENV_PATH`
disables this discovery and uses that base path only.

* `.env`: Default.
* `.env.local`: Local overrides. This file is loaded for all environments except test.
* `.env.development`, `.env.test`, `.env.production`: Environment-specific settings.
* `.env.development.local`, `.env.test.local`, `.env.production.local`: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

* `npm start`: `.env.development.local`, `.env.local`, `.env.development`, `.env`
* `npm test`: `.env.test.local`, `.env.test`, `.env` (note `.env.local` is missing)

[CRA Reference](https://create-react-app.dev/docs/adding-custom-environment-variables/#what-other-env-files-can-be-used)

### Typing Environment Variables

To add new entries, you augment `Env` from `@wolfstar/env-utilities/dist/lib/types` using any of the following types:

* `BooleanString`: can be parsed with `envParseBoolean`.
* `IntegerString`: can be parsed with `envParseInteger`.
* `NumberString`: can be parsed with `envParseNumber`.
* `string`: can be parsed with `envParseString` and `envParseArray`.

The above 5 functions will throw an `ReferenceError` instance if a key is missing (unless a default is passed in the second parameter) as well as a `TypeError` instance if a key could not be parsed. The default value is returned as-is and is not validated.

An example of adding more keys is as it follows:

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

declare module '@wolfstar/env-utilities' {
	interface Env {
		// Accepts 'true' or 'false':
		ENABLE_TELEMETRY: BooleanString;

		// Accepts any integer, e.g. '10':
		REFRESH_INTERVAL: IntegerString;

		// Accepts any number, e.g. '1.5':
		MINIMUM_SPEED: NumberString;

		// Accepts any string:
		APPLICATION_SECRET: string;
	}
}
```