@idealyst/config 1.2.13 → 1.2.15

package/README.md

@@ -6,8 +6,8 @@ Cross-platform configuration for React and React Native with env inheritance sup
 
 - **Single API** - Same code works on web and native
 - **Env inheritance** - Shared config with platform-specific overrides
+- **Babel plugin** - Config injected at build time, no runtime overhead
 - **Type-safe** - Auto-generated TypeScript declarations
-- **Bundler agnostic** - No bundler configuration needed
 - **Monorepo friendly** - Designed for shared/web/mobile patterns
 
 ## Installation
@@ -54,75 +54,97 @@ API_URL=https://web-api.example.com
 ANALYTICS_ENABLED=false
 ```
 
-### 2. Generate config
-
-```bash
-# In packages/web/
-npx idealyst-config generate --extends ../shared/.env --env .env
-
-# In packages/mobile/
-npx idealyst-config generate --extends ../shared/.env --env .env
+### 2. Add Babel plugin
+
+**babel.config.js:**
+```js
+module.exports = {
+  presets: ['...'],
+  plugins: [
+    ['@idealyst/config/plugin', {
+      extends: ['../shared/.env'],
+      envPath: '.env'
+    }]
+  ]
+}
 ```
 
-This creates `src/config.generated.ts` with merged values:
+### 3. Use in your app
 
 ```typescript
-// Web: API_URL overridden, others inherited
-export const generatedConfig = {
-  API_URL: "https://web-api.example.com",
-  GOOGLE_CLIENT_ID: "abc123",
-  ANALYTICS_ENABLED: "true"
-}
+import { config } from '@idealyst/config'
+
+// Values are injected at build time!
+const apiUrl = config.get('API_URL')
+const analyticsEnabled = config.get('ANALYTICS_ENABLED') === 'true'
 ```
 
-### 3. Initialize and use
+That's it! The Babel plugin reads your .env files at compile time and injects the values automatically.
 
-```typescript
-// In your app entry point (e.g., App.tsx, main.tsx)
-import { setConfig } from '@idealyst/config'
-import { generatedConfig } from './config.generated'
+## Babel Plugin Options
 
-setConfig(generatedConfig)
-```
+```js
+['@idealyst/config/plugin', {
+  // Inherit from these .env files (lowest to highest priority)
+  extends: ['../shared/.env', '../common/.env'],
 
-```typescript
-// Anywhere in your app
-import { config } from '@idealyst/config'
+  // Main .env file (highest priority, default: auto-detect)
+  envPath: '.env',
 
-const apiUrl = config.get('API_URL')
-const analyticsEnabled = config.get('ANALYTICS_ENABLED') === 'true'
+  // Required keys - warn if missing at build time
+  required: ['API_URL', 'AUTH_SECRET'],
+
+  // Fail the build if required keys are missing (default: false = warn only)
+  errorOnMissing: true,
+
+  // Log which .env files were loaded (default: false)
+  verbose: true,
+
+  // Project root (default: process.cwd())
+  root: '/path/to/project'
+}]
 ```
 
-## CLI Reference
+### Build-time Validation
 
-```bash
-idealyst-config generate [options]
+The plugin validates required keys at compile time:
+
+```js
+// babel.config.js
+plugins: [
+  ['@idealyst/config/plugin', {
+    required: ['API_URL', 'DATABASE_URL', 'JWT_SECRET'],
+    errorOnMissing: process.env.NODE_ENV === 'production'  // Fail in prod, warn in dev
+  }]
+]
+```
 
-Options:
-  --env <path>        Path to .env file (default: auto-detect)
-  --extends <path>    Inherit from another .env (can use multiple times)
-  --output <path>     Output path (default: src/config.generated.ts)
-  --types-only        Generate only .d.ts file, no values
-  --help              Show help
+**Warning output:**
+```
+⚠ @idealyst/config: Missing required config keys: JWT_SECRET
+  Add these keys to your .env file to suppress this warning.
+  Set errorOnMissing: true to fail the build instead.
 ```
 
-### Examples
+**Error output (with `errorOnMissing: true`):**
+```
+✖ @idealyst/config: Missing required config keys: JWT_SECRET
+  Add these keys to your .env file or check your plugin configuration.
 
-```bash
-# Simple - auto-detect .env
-idealyst-config generate
+Error: @idealyst/config: Missing required config keys: JWT_SECRET
+```
 
-# With shared inheritance
-idealyst-config generate --extends ../shared/.env --env .env
+### Auto-detection
 
-# Multiple inheritance (lowest to highest priority)
-idealyst-config generate \
-  --extends ../../shared/.env \
-  --extends ../.env.common \
-  --env .env
+If you don't specify options, the plugin will:
+1. Auto-detect `.env.local`, `.env.development`, or `.env` in your project
+2. Auto-detect `../shared/.env` or `../../shared/.env` for inheritance
 
-# Types only (for CI/type checking without values)
-idealyst-config generate --types-only --output src/env.d.ts
+```js
+// Minimal config - auto-detects everything
+plugins: [
+  '@idealyst/config/plugin'
+]
 ```
 
 ## Inheritance Priority
@@ -130,9 +152,49 @@ idealyst-config generate --types-only --output src/env.d.ts
 Configs are merged in order, with later files overriding earlier ones:
 
 ```
-1. --extends ../shared/.env     (lowest priority)
-2. --extends ../.env.common
-3. --env .env                   (highest priority)
+1. extends[0]: ../shared/.env     (lowest priority)
+2. extends[1]: ../common/.env
+3. envPath: .env                  (highest priority)
+```
+
+## Vite Setup
+
+For Vite projects, add to `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          ['@idealyst/config/plugin', {
+            extends: ['../shared/.env'],
+            envPath: '.env'
+          }]
+        ]
+      }
+    })
+  ]
+})
+```
+
+## React Native / Metro Setup
+
+Add to `babel.config.js`:
+
+```js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: [
+    ['@idealyst/config/plugin', {
+      extends: ['../shared/.env'],
+      envPath: '.env'
+    }]
+  ]
+}
 ```
 
 ## API Reference
@@ -180,38 +242,17 @@ config.validate(['API_URL', 'AUTH_SECRET'])
 // Throws ConfigValidationError if any are missing
 ```
 
-### `setConfig(config: Record<string, string>)`
-
-Initialize config values (call once at app startup).
-
-```typescript
-import { setConfig } from '@idealyst/config'
-import { generatedConfig } from './config.generated'
-
-setConfig(generatedConfig)
-```
-
-## React Native Setup
-
-1. Install react-native-config:
-```bash
-npm install react-native-config
-cd ios && pod install
-```
+## Type Generation (Optional)
 
-2. Follow [react-native-config setup](https://github.com/luggit/react-native-config#setup)
+For TypeScript autocomplete, generate type declarations:
 
-3. Generate and use the same way as web:
 ```bash
-idealyst-config generate --extends ../shared/.env --env .env
+npx idealyst-config generate --extends ../shared/.env --env .env --types-only
 ```
 
-## Type Safety
-
-The CLI generates TypeScript declarations for autocomplete:
+This creates `src/config.generated.d.ts`:
 
 ```typescript
-// Generated: src/config.generated.d.ts
 declare module '@idealyst/config' {
   interface ConfigKeys {
     API_URL: string
@@ -221,27 +262,47 @@ declare module '@idealyst/config' {
 }
 ```
 
-This provides autocomplete and catches typos at compile time.
-
-## Build Integration
-
-Add to your build scripts:
+Add to your build script for automatic updates:
 
 ```json
 {
   "scripts": {
-    "prebuild": "idealyst-config generate --extends ../shared/.env",
-    "build": "vite build"
+    "prebuild": "idealyst-config generate --extends ../shared/.env --types-only"
   }
 }
 ```
 
+## How It Works
+
+The Babel plugin transforms your code at compile time:
+
+**Input:**
+```typescript
+import { config } from '@idealyst/config'
+
+const apiUrl = config.get('API_URL')
+```
+
+**Output (after Babel):**
+```typescript
+import { config, setConfig as __idealyst_setConfig } from '@idealyst/config'
+__idealyst_setConfig({ API_URL: "https://api.example.com", GOOGLE_CLIENT_ID: "abc123" })
+
+const apiUrl = config.get('API_URL')
+```
+
+This means:
+- **No runtime .env parsing** - values are baked in at build time
+- **Works with any bundler** - Vite, Webpack, Metro, esbuild
+- **Tree-shakeable** - unused config keys can be eliminated
+- **Secure** - .env files never shipped to client
+
 ## Best Practices
 
-1. **Generate before build** - Add to prebuild script
-2. **Gitignore generated files** - Add `config.generated.ts` to `.gitignore`
-3. **Commit .env.example** - Document required keys without values
-4. **Validate at startup** - Use `config.validate()` early
+1. **Gitignore .env files** - Never commit secrets
+2. **Commit .env.example** - Document required keys
+3. **Use shared config** - DRY principle for common values
+4. **Validate at startup** - Catch missing config early
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/config",
-  "version": "1.2.13",
+  "version": "1.2.15",
   "description": "Cross-platform configuration and environment variable support for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/config#readme",
   "readme": "README.md",
@@ -35,6 +35,10 @@
         "require": "./src/index.ts"
       }
     },
+    "./plugin": {
+      "require": "./plugin.js",
+      "default": "./plugin.js"
+    },
     "./generate": {
       "types": "./src/cli/generate.ts",
       "import": "./src/cli/generate.ts",
@@ -61,6 +65,7 @@
   "files": [
     "src",
     "bin",
+    "plugin.js",
     "README.md"
   ],
   "keywords": [

package/plugin.js

@@ -0,0 +1,293 @@
+/**
+ * @idealyst/config Babel plugin
+ *
+ * Injects config values at compile time from .env files.
+ *
+ * Usage in babel.config.js:
+ * ```js
+ * module.exports = {
+ *   plugins: [
+ *     ['@idealyst/config/plugin', {
+ *       extends: ['../shared/.env'],
+ *       envPath: '.env',
+ *       required: ['API_URL', 'AUTH_SECRET'],  // Warn if missing
+ *       errorOnMissing: true                    // Fail build if missing
+ *     }]
+ *   ]
+ * }
+ * ```
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// Track if we've already validated (to avoid duplicate warnings)
+let hasValidated = false
+
+/**
+ * Parse a .env file and extract key-value pairs.
+ */
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {}
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8')
+  const config = {}
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue
+    }
+
+    const equalsIndex = trimmed.indexOf('=')
+    if (equalsIndex === -1) {
+      continue
+    }
+
+    let key = trimmed.substring(0, equalsIndex).trim()
+    let value = trimmed.substring(equalsIndex + 1).trim()
+
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    }
+
+    // Strip VITE_ prefix to normalize
+    if (key.startsWith('VITE_')) {
+      key = key.substring(5)
+    }
+
+    config[key] = value
+  }
+
+  return config
+}
+
+/**
+ * Find .env file in directory.
+ */
+function findEnvFile(directory) {
+  const candidates = ['.env.local', '.env.development', '.env']
+  for (const candidate of candidates) {
+    const envPath = path.join(directory, candidate)
+    if (fs.existsSync(envPath)) {
+      return envPath
+    }
+  }
+  return null
+}
+
+/**
+ * Look for shared .env in common monorepo locations.
+ */
+function findSharedEnv(directory) {
+  const patterns = [
+    '../shared/.env',
+    '../../shared/.env',
+    '../../packages/shared/.env',
+  ]
+  for (const pattern of patterns) {
+    const sharedPath = path.resolve(directory, pattern)
+    if (fs.existsSync(sharedPath)) {
+      return sharedPath
+    }
+  }
+  return null
+}
+
+/**
+ * Load and merge config from .env files.
+ */
+function loadConfig(options, projectRoot) {
+  const configs = []
+  const sources = []
+
+  // Load inherited configs first (lowest priority)
+  if (options.extends) {
+    for (const extendPath of options.extends) {
+      const resolvedPath = path.isAbsolute(extendPath)
+        ? extendPath
+        : path.resolve(projectRoot, extendPath)
+
+      if (fs.existsSync(resolvedPath)) {
+        configs.push(parseEnvFile(resolvedPath))
+        sources.push(resolvedPath)
+      }
+    }
+  } else {
+    // Auto-detect shared env
+    const sharedEnv = findSharedEnv(projectRoot)
+    if (sharedEnv) {
+      configs.push(parseEnvFile(sharedEnv))
+      sources.push(sharedEnv)
+    }
+  }
+
+  // Load main env file (highest priority)
+  let envPath = null
+  if (options.envPath) {
+    envPath = path.isAbsolute(options.envPath)
+      ? options.envPath
+      : path.resolve(projectRoot, options.envPath)
+  } else {
+    envPath = findEnvFile(projectRoot)
+  }
+
+  if (envPath && fs.existsSync(envPath)) {
+    configs.push(parseEnvFile(envPath))
+    sources.push(envPath)
+  }
+
+  // Merge configs (later configs override earlier ones)
+  return {
+    config: Object.assign({}, ...configs),
+    sources
+  }
+}
+
+/**
+ * Validate required config keys and emit warnings/errors.
+ */
+function validateConfig(configValues, options, projectRoot) {
+  if (hasValidated) return true
+  hasValidated = true
+
+  const required = options.required || []
+  if (required.length === 0) return true
+
+  const missing = required.filter(key => !(key in configValues))
+
+  if (missing.length === 0) return true
+
+  const errorOnMissing = options.errorOnMissing ?? false
+  const message = `@idealyst/config: Missing required config keys: ${missing.join(', ')}`
+
+  if (errorOnMissing) {
+    console.error('\n\x1b[31m✖ ' + message + '\x1b[0m')
+    console.error('\x1b[90m  Add these keys to your .env file or check your plugin configuration.\x1b[0m\n')
+    throw new Error(message)
+  } else {
+    console.warn('\n\x1b[33m⚠ ' + message + '\x1b[0m')
+    console.warn('\x1b[90m  Add these keys to your .env file to suppress this warning.\x1b[0m')
+    console.warn('\x1b[90m  Set errorOnMissing: true to fail the build instead.\x1b[0m\n')
+  }
+
+  return false
+}
+
+/**
+ * Babel plugin that injects config values at compile time.
+ */
+module.exports = function babelPluginIdealystConfig(babel) {
+  const { types: t } = babel
+
+  // Cache config per project root
+  const configCache = new Map()
+
+  // Reset validation state on new compilation
+  hasValidated = false
+
+  return {
+    name: '@idealyst/config',
+
+    visitor: {
+      Program: {
+        enter(programPath, state) {
+          const opts = state.opts || {}
+          const projectRoot = opts.root || state.cwd || process.cwd()
+
+          // Load config (cached per project root)
+          let configValues
+          if (!configCache.has(projectRoot)) {
+            const { config, sources } = loadConfig(opts, projectRoot)
+            configCache.set(projectRoot, config)
+            configValues = config
+
+            // Validate required keys (only once per build)
+            validateConfig(config, opts, projectRoot)
+
+            // Log loaded sources in verbose mode
+            if (opts.verbose && sources.length > 0) {
+              console.log('\x1b[36m@idealyst/config loaded:\x1b[0m')
+              sources.forEach(s => console.log('  ← ' + path.relative(projectRoot, s)))
+              console.log('  Keys:', Object.keys(config).join(', '))
+            }
+          } else {
+            configValues = configCache.get(projectRoot)
+          }
+
+          // Track if this file imports from @idealyst/config
+          let hasConfigImport = false
+          let configImportPath = null
+
+          // Find imports from @idealyst/config
+          programPath.traverse({
+            ImportDeclaration(importPath) {
+              if (importPath.node.source.value === '@idealyst/config') {
+                hasConfigImport = true
+                configImportPath = importPath
+              }
+            }
+          })
+
+          if (!hasConfigImport || !configImportPath) {
+            return
+          }
+
+          // Check if setConfig is already imported
+          let hasSetConfigImport = false
+          let setConfigLocalName = '__idealyst_setConfig'
+
+          for (const specifier of configImportPath.node.specifiers) {
+            if (t.isImportSpecifier(specifier) &&
+                t.isIdentifier(specifier.imported) &&
+                specifier.imported.name === 'setConfig') {
+              hasSetConfigImport = true
+              setConfigLocalName = specifier.local.name
+              break
+            }
+          }
+
+          // Add setConfig to imports if not already present
+          if (!hasSetConfigImport) {
+            configImportPath.node.specifiers.push(
+              t.importSpecifier(
+                t.identifier('__idealyst_setConfig'),
+                t.identifier('setConfig')
+              )
+            )
+          }
+
+          // Create the config object literal
+          const configProperties = Object.entries(configValues).map(([key, value]) =>
+            t.objectProperty(t.identifier(key), t.stringLiteral(value))
+          )
+          const configObject = t.objectExpression(configProperties)
+
+          // Create setConfig call
+          const setConfigCall = t.expressionStatement(
+            t.callExpression(
+              t.identifier(setConfigLocalName),
+              [configObject]
+            )
+          )
+
+          // Insert after the import statement
+          const importIndex = programPath.node.body.indexOf(configImportPath.node)
+          programPath.node.body.splice(importIndex + 1, 0, setConfigCall)
+        }
+      }
+    }
+  }
+}
+
+// Export utilities for direct use
+module.exports.parseEnvFile = parseEnvFile
+module.exports.loadConfig = loadConfig
+module.exports.findEnvFile = findEnvFile
+module.exports.findSharedEnv = findSharedEnv
+module.exports.validateConfig = validateConfig

package/src/config.native.ts

@@ -1,32 +1,63 @@
 import type { IConfig } from './types'
 import { ConfigValidationError } from './types'
 
-// react-native-config provides a Config object with all env variables
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-let RNConfig: Record<string, string | undefined> = {}
-
-try {
-  // Dynamic import to handle cases where react-native-config is not installed
-  // This allows the package to be used in web-only projects without errors
-  RNConfig = require('react-native-config').default || require('react-native-config')
-} catch {
-  // react-native-config not available - will be empty object
-  // This is expected in web environments or when the native module isn't linked
+/**
+ * Config store - initialized from react-native-config, can be overridden via setConfig().
+ */
+let configStore: Record<string, string> = {}
+
+/**
+ * Initialize from react-native-config if available.
+ */
+function initFromRNConfig(): void {
+  try {
+    // Dynamic import to handle cases where react-native-config is not installed
+    const RNConfig = require('react-native-config').default || require('react-native-config')
+    if (RNConfig && typeof RNConfig === 'object') {
+      configStore = { ...RNConfig }
+    }
+  } catch {
+    // react-native-config not available - configStore remains empty
+    // Values will be injected by Babel plugin via setConfig()
+  }
 }
 
+// Initialize on module load
+initFromRNConfig()
+
 /**
- * Native implementation of IConfig using react-native-config.
- *
- * This implementation provides direct access to .env variables without
- * any prefix transformation, as react-native-config doesn't require prefixes.
+ * Set config values. Called by Babel plugin at compile time,
+ * or can be called manually.
+ */
+export function setConfig(config: Record<string, string>): void {
+  configStore = { ...configStore, ...config }
+}
+
+/**
+ * Clear all config values. Useful for testing.
+ */
+export function clearConfig(): void {
+  configStore = {}
+}
+
+/**
+ * Get the raw config store. Useful for debugging.
+ */
+export function getConfigStore(): Record<string, string> {
+  return { ...configStore }
+}
+
+/**
+ * Native implementation of IConfig.
  *
- * The .env file should use canonical names:
- * API_URL=https://api.example.com
- * GOOGLE_CLIENT_ID=abc123
+ * Config values come from:
+ * 1. react-native-config (if installed)
+ * 2. Babel plugin injection via setConfig()
+ * 3. Manual setConfig() calls
  */
 class NativeConfig implements IConfig {
   get(key: string, defaultValue?: string): string | undefined {
-    return RNConfig[key] ?? defaultValue
+    return configStore[key] ?? defaultValue
   }
 
   getRequired(key: string): string {
@@ -41,11 +72,11 @@ class NativeConfig implements IConfig {
   }
 
   has(key: string): boolean {
-    return RNConfig[key] !== undefined
+    return configStore[key] !== undefined
   }
 
   keys(): string[] {
-    return Object.keys(RNConfig)
+    return Object.keys(configStore).sort()
   }
 
   validate(requiredKeys: string[]): void {

package/src/index.native.ts

@@ -1,8 +1,9 @@
 /**
  * Native entry point for @idealyst/config
  *
- * Uses react-native-config for environment variable access.
- * No prefix is required - use canonical names directly.
+ * Config values come from:
+ * 1. react-native-config (if installed)
+ * 2. Babel plugin injection via setConfig()
  *
  * @example
  * ```typescript
@@ -13,11 +14,11 @@
  * ```
  */
 
-import NativeConfig from './config.native'
+import NativeConfig, { setConfig, clearConfig, getConfigStore } from './config.native'
 
 // Create singleton instance for native
 const config = new NativeConfig()
 
 export default config
-export { config, config as Config, NativeConfig }
+export { config, config as Config, NativeConfig, setConfig, clearConfig, getConfigStore }
 export * from './types'