Bootstrap

Prepare CLI environments with platform-aware directory resolution, file discovery, and .env loading in a single utility.

Summary

The Bootstrap battery resolves platform-specific directories (XDG on macOS and Linux, AppData on Windows), discovers configuration files across a prioritized search path, and loads .env files into process.env without overriding existing values.

Why Use This Battery?

Eliminates duplicated path-resolution logic across projects by centralizing directory and file discovery in one place.
Handles cross-platform differences automatically so CLI tools work on macOS, Linux, and Windows without conditional code.
Loads .env files with a single call, supporting comments, quoted values, and non-destructive merging.

Capabilities

Resolves app-scoped directories for configuration, data, and cache storage across all major platforms.
Discovers files across a configurable search order using keywords like cwd, config-dir, data-dir, cache-dir, home, temp, and project-root.
Accepts absolute paths alongside keywords for custom search locations.
Creates directories automatically when accessed through app-scoped getter methods (getConfigDir, getDataDir, getCacheDir).
Logs .env loading activity through Logger.debug for development visibility.

Usage

Good to Know

Examples use TypeScript, but the API is identical in JavaScript (ESM-only).

Settings

Bootstrap uses method arguments and standard environment variables rather than a separate config object.

Setting or argument	Used by	Default	Description
`appName`	Directory getters and file resolvers	—	Required application namespace appended to platform-managed directories.
`filename`	`resolveFileDir`, `resolveFileDirs`	—	Required file name searched for in each resolved location.
`searchOrder`	`resolveFileDir`, `resolveFileDirs`	—	Required ordered array of search keywords or absolute directory paths.
`directory`	`loadEnv`	—	Required directory containing the `.env` file to load.
`XDG_CONFIG_HOME`	`getConfigDir` on macOS and Linux	Platform path	Overrides the base configuration directory.
`XDG_DATA_HOME`	`getDataDir` on Linux	`~/.local/share`	Overrides the base data directory.
`XDG_CACHE_HOME`	`getCacheDir` on Linux	`~/.cache`	Overrides the base cache directory.
`APPDATA`	Config and data getters on Windows	Windows profile path	Overrides the roaming application-data directory.
`LOCALAPPDATA`	`getCacheDir` on Windows	Windows profile path	Overrides the local application-data directory.

Output Examples

Search Keywords

The searchOrder parameter in resolveFileDir and resolveFileDirs accepts these keywords alongside absolute path strings.

Keyword	Resolves to
`cwd`	Current working directory
`config-dir`	App-scoped configuration directory
`data-dir`	App-scoped data directory
`cache-dir`	App-scoped cache directory
`home`	User home directory
`temp`	System temporary directory
`project-root`	Monorepo root, nearest `package.json` parent, or `cwd`

App-scoped keywords (config-dir, data-dir, cache-dir) use the appName parameter to build the full path.

Cross-Platform Directories

Getter	macOS	Linux	Windows
`getConfigDir`	`~/.config/<app>`	`~/.config/<app>`	`%APPDATA%/<app>`
`getDataDir`	`~/Library/Application Support/<app>`	`~/.local/share/<app>`	`%APPDATA%/<app>`
`getCacheDir`	`~/Library/Caches/<app>`	`~/.cache/<app>`	`%LOCALAPPDATA%/Temp/<app>`

XDG_CONFIG_HOME is respected on macOS and Linux. XDG_DATA_HOME and XDG_CACHE_HOME are respected on Linux only — macOS uses native ~/Library paths.

APPDATA and LOCALAPPDATA are respected on Windows.

.env File Format

Supported syntax for files loaded by loadEnv.

ini

# Comment lines are ignored
KEY=value
KEY="double quoted value"
KEY='single quoted value'

# Empty lines are ignored

Variables already present in process.env are not overridden.

Troubleshooting

.env is not being loaded

Confirm the file exists in the directory passed to loadEnv. Set LOG_LEVEL=debug to see the search output in the terminal.

Directory getters return unexpected paths

Check whether XDG_CONFIG_HOME (macOS and Linux), XDG_DATA_HOME (Linux only), or XDG_CACHE_HOME (Linux only) environment variables are set. These override the default paths shown in the table above.

File not found despite existing on disk

Verify the searchOrder includes the correct keyword or absolute path. Use resolveFileDirs to see all matching locations.