feat: add deep env variable support

chore: wip

chore: wip

Author: chrisbbreuer

README.md

@@ -16,6 +16,7 @@
 - 🌐 **Universal**: _optimized for both Bun & browser environments_
 - 🪶 **Lightweight**: _zero dependencies, built on native modules_
 - 💪 **Type-Safe**: _fully typed configurations with generated type definitions_
+- 🌍 **Environment Variables**: _automatic environment variable support based on config name_
 - 🛠️ **CLI Tools**: _powerful & easy-to-use CLI_
 - 📦 **Flexible**: _supports multiple config file formats (.ts, .js, .mjs, .cjs, .json, .mts, .cts)_
 
@@ -57,6 +58,60 @@ console.log(resolvedConfig) // { port: 3000, host: 'localhost' }, unless a confi
 > [!TIP]
 > If your `process.cwd()` includes a `$name.config.{ts,js,mjs,cjs,json}` _(or `.$name.config.{ts,js,mjs,cjs,json}`)_ file, it will be loaded and merged with defaults, where file config file values take precedence. For minimalists, it also loads a `.$name.{ts,js,mjs,cjs,json}` and `$name.{ts,js,mjs,cjs,json}` file if present.
 
+### Environment Variables
+
+Bunfig automatically checks for environment variables based on the config name. Environment variables take precedence over default values but are overridden by config files.
+
+You can disable this feature by setting `checkEnv: false` in your config options:
+
+```ts
+const options = {
+  name: 'my-app',
+  defaultConfig: { /* ... */ },
+  checkEnv: false, // Disable environment variable checking
+}
+```
+
+The naming convention for environment variables is:
+```
+[CONFIG_NAME]_[PROPERTY_NAME]
+```
+
+For nested properties, use underscores to separate the levels:
+```
+[CONFIG_NAME]_[NESTED_PROPERTY_PATH]
+```
+
+Example:
+
+```ts
+// With a config name of "my-app"
+const options = {
+  name: 'my-app',
+  defaultConfig: {
+    port: 3000,
+    host: 'localhost',
+    database: {
+      url: 'postgres://localhost:5432',
+      user: 'admin',
+    },
+  },
+}
+
+// These environment variables would be automatically used if set:
+// MY_APP_PORT=8080
+// MY_APP_HOST=example.com
+// MY_APP_DATABASE_URL=postgres://production:5432
+// MY_APP_DATABASE_USER=prod_user
+```
+
+For array values, you can use a JSON string or comma-separated values:
+```
+MY_APP_ALLOWED_ORIGINS=["https://example.com","https://api.example.com"]
+// or
+MY_APP_ALLOWED_ORIGINS=https://example.com,https://api.example.com
+```
+
 ### Browser Environment
 
 For browser environments, use the `loadConfig` function from the browser-specific entry point to load your configuration from an API endpoint:

bun.lock

@@ -2,7 +2,6 @@ import type { HeadConfig } from 'vitepress'
 import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { withPwa } from '@vite-pwa/vitepress'
 import { defineConfig } from 'vitepress'
-
 import vite from './vite.config'
 
 // https://vitepress.dev/reference/site-config
@@ -62,6 +61,7 @@ const sidebar = [
     text: 'Features',
     items: [
       { text: 'Configuration Loading', link: '/features/configuration-loading' },
+      { text: 'Environment Variables', link: '/features/environment-variables' },
       { text: 'Type Safety', link: '/features/type-safety' },
     ],
   },

docs/.vitepress/config.ts

@@ -24,6 +24,52 @@ const config = await loadConfig<MyConfig>({
 })
 ```
 
+### Environment Variables in Browser Context
+
+While the automatic environment variable loading feature works great in server-side environments, browsers don't have direct access to system environment variables. In browser environments:
+
+1. Environment variables can only be accessed if they are:
+   - Embedded during the build process by tools like Vite or webpack (e.g., replacing `process.env.API_URL` with the actual value)
+   - Made available through the API endpoint that serves your configuration
+
+2. The `checkEnv` option is supported for API consistency, but has little effect unless you've embedded environment variables at build time
+
+3. Common patterns for using environment-specific configuration in browsers include:
+   - Using different API endpoints for different environments
+   - Having the server inject environment variables into the initial page
+   - Using build-time environment variables for configuration generation
+
+```ts
+// In a browser context with build tool that supports env variables
+// If you're using Vite, for example, import.meta.env would contain these values
+const apiEndpoint = process.env.API_ENDPOINT || '/api/config'
+
+const config = await loadConfig<MyConfig>({
+  name: 'my-app',
+  endpoint: apiEndpoint,
+  defaultConfig: { /* ... */ },
+})
+```
+
+For a universal (isomorphic) approach that works in both server and browser contexts, you can implement a pattern like this:
+
+```ts
+import { isBrowser } from 'bunfig/browser'
+
+async function getConfig() {
+  if (isBrowser()) {
+    // Browser: load from API
+    const { loadConfig } = await import('bunfig/browser')
+    return loadConfig({ endpoint: '/api/config', /* ... */ })
+  }
+  else {
+    // Server: use file-based config with env vars
+    const { loadConfig } = await import('bunfig')
+    return loadConfig({ name: 'my-app', /* ... */ })
+  }
+}
+```
+
 ### Custom Headers
 
 You can include custom headers in your configuration requests:

docs/advanced/browser-support.md

@@ -2,6 +2,16 @@
 
 bunfig provides a powerful and flexible configuration loading system that automatically finds and loads your configuration files from multiple possible locations and formats.
 
+## Configuration Resolution Order
+
+bunfig resolves configuration in a priority order, giving you flexibility across different environments:
+
+1. Default configuration values (provided in code)
+2. Environment variables (automatically detected based on config name)
+3. Configuration files (loaded from the filesystem)
+
+This order ensures that values from higher priority sources override lower priority ones, allowing for a layered configuration approach.
+
 ## Smart File Resolution
 
 bunfig will search for your configuration file in the following order:
@@ -19,6 +29,23 @@ For example, if your `name` is "my-app", it will look for:
 - `.my-app.ts`
 (and the same for other supported extensions)
 
+## Environment Variable Support
+
+bunfig automatically checks for environment variables based on your configuration name, making it easy to override settings in different environments. Environment variables follow this naming pattern:
+
+```
+[CONFIG_NAME]_[PROPERTY_NAME]
+```
+
+For example, with a config name of "my-app", these environment variables would be recognized:
+
+```bash
+MY_APP_PORT=8080
+MY_APP_HOST=production.example.com
+```
+
+Environment variables are automatically converted to the correct type based on your default configuration. See the [Environment Variables](./environment-variables.md) section for more details.
+
 ## Supported Formats
 
 bunfig supports multiple configuration file formats:
@@ -29,7 +56,7 @@ bunfig supports multiple configuration file formats:
 
 ## Deep Merging
 
-When loading configuration, bunfig intelligently merges your default configuration with the values from your configuration file:
+When loading configuration, bunfig intelligently merges your default configuration with the values from environment variables and your configuration file:
 
 ```ts
 // Default configuration
@@ -43,10 +70,13 @@ const defaultConfig = {
   },
 }
 
+// Environment variables
+// MY_APP_SERVER_PORT=8080
+
 // my-app.config.ts
 export default {
   server: {
-    port: 8080,
+    host: 'custom.example.com',
   },
   features: {
     auth: true,
@@ -56,8 +86,8 @@ export default {
 // Result after merging
 const result = {
   server: {
-    port: 8080, // From config file
-    host: 'localhost', // From default config
+    port: 8080, // From environment variable
+    host: 'custom.example.com', // From config file (overrides env var if set)
   },
   features: {
     auth: true, // From config file
@@ -69,9 +99,9 @@ const result = {
 
 bunfig handles various error scenarios gracefully:
 
-- Missing configuration files: Returns the default configuration
+- Missing configuration files: Returns the default configuration with environment variables applied
 - Invalid file formats: Skips the file and continues searching
-- Type mismatches: Returns the default configuration
+- Type mismatches: Returns the default configuration with environment variables applied
 - File system errors: Properly caught and handled
 
 ## Working Directory Support
@@ -89,3 +119,15 @@ const config = await loadConfig<MyConfig>({
 ```
 
 This allows you to organize your configuration files in a dedicated directory structure.
+
+## Disabling Features
+
+You can disable certain features of the configuration loader if needed:
+
+```ts
+const config = await loadConfig<MyConfig>({
+  name: 'my-app',
+  defaultConfig: { /* ... */ },
+  checkEnv: false, // Disable environment variable loading
+})
+```

docs/features/configuration-loading.md

@@ -0,0 +1,153 @@
+# Environment Variables
+
+Bunfig automatically checks for environment variables based on the config name. This makes it easy to override configuration values without modifying your config files, which is particularly useful for:
+
+- Different deployment environments (development, staging, production)
+- CI/CD pipelines
+- Containerized applications
+- Secrets management
+
+## How It Works
+
+Environment variables take precedence over default values but are overridden by config files. This priority order allows for flexible configuration:
+
+1. Default values (lowest priority)
+2. Environment variables (middle priority)
+3. Config files (highest priority)
+
+## Naming Convention
+
+The naming convention for environment variables follows this pattern:
+
+```
+[CONFIG_NAME]_[PROPERTY_NAME]
+```
+
+For nested properties, use underscores to separate the levels:
+
+```
+[CONFIG_NAME]_[NESTED_PROPERTY_PATH]
+```
+
+All keys are automatically converted to uppercase with hyphens replaced by underscores.
+
+### Examples
+
+With a config name of "my-app" and the following default configuration:
+
+```ts
+const options = {
+  name: 'my-app',
+  defaultConfig: {
+    port: 3000,
+    host: 'localhost',
+    database: {
+      url: 'postgres://localhost:5432',
+      user: 'admin',
+    },
+    features: {
+      logging: {
+        enabled: true,
+        level: 'info',
+      },
+    },
+  },
+}
+```
+
+These environment variables would be automatically detected:
+
+```bash
+# Top-level properties
+MY_APP_PORT=8080
+MY_APP_HOST=example.com
+
+# Nested properties
+MY_APP_DATABASE_URL=postgres://production:5432
+MY_APP_DATABASE_USER=prod_user
+MY_APP_FEATURES_LOGGING_ENABLED=false
+MY_APP_FEATURES_LOGGING_LEVEL=error
+```
+
+## Data Type Conversion
+
+Bunfig automatically converts environment variables to the appropriate type based on the default value:
+
+- **Numbers**: Environment variable values are converted to numbers
+- **Booleans**: `"true"` (case-insensitive) is converted to `true`, everything else to `false`
+- **Arrays**: Two formats are supported:
+  - JSON arrays: `MY_APP_ALLOWED_ORIGINS=["https://example.com","https://api.example.com"]`
+  - Comma-separated values: `MY_APP_ALLOWED_ORIGINS=https://example.com,https://api.example.com`
+- **Strings**: Used as-is
+
+## Disabling Environment Variable Support
+
+You can disable environment variable checking by setting `checkEnv: false` in your config options:
+
+```ts
+const options = {
+  name: 'my-app',
+  defaultConfig: { /* ... */ },
+  checkEnv: false, // Disable environment variable checking
+}
+```
+
+## Browser Support
+
+In browser environments, environment variables function differently since browser JavaScript doesn't have direct access to system environment variables. In this context:
+
+- Server-side environment variables can be embedded during build time
+- You can pass environment configuration via the API endpoint specified in `loadConfig`
+
+For browser applications, consider using environment variables during your build process to configure the endpoint URL:
+
+```ts
+const config = await loadConfig({
+  name: 'my-app',
+  endpoint: process.env.API_ENDPOINT || '/api/config',
+  defaultConfig: { /* ... */ },
+})
+```
+
+## Best Practices
+
+1. **Use environment variables for environment-specific settings**: ports, hosts, API keys, feature flags
+2. **Don't use environment variables for complex objects**: They work best for primitive values or simple arrays
+3. **Document your environment variables**: Include all supported environment variables in your README
+4. **Provide sensible defaults**: Make sure your application works with the default configuration
+
+## Example: Complete Configuration Flow
+
+```ts
+// 1. Default configuration in code
+const defaultConfig = {
+  port: 3000,
+  debug: false,
+  api: {
+    url: 'https://api.example.com',
+    timeout: 5000,
+  },
+}
+
+// 2. Environment variables can override defaults
+// MY_APP_PORT=8080
+// MY_APP_API_URL=https://staging-api.example.com
+
+// 3. Config file has highest priority (my-app.config.ts)
+export default {
+  debug: true,
+  api: {
+    timeout: 10000,
+  },
+}
+
+// Final resolved configuration:
+{
+  port: 8080,              // From environment variable
+  debug: true,             // From config file
+  api: {
+    url: 'https://staging-api.example.com', // From environment variable
+    timeout: 10000,        // From config file
+  },
+}
+```