@idealyst/config 1.2.13 → 1.2.14

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,59 @@ 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
-```
-
-This creates `src/config.generated.ts` with merged values:
-
-```typescript
-// Web: API_URL overridden, others inherited
-export const generatedConfig = {
-  API_URL: "https://web-api.example.com",
-  GOOGLE_CLIENT_ID: "abc123",
-  ANALYTICS_ENABLED: "true"
+### 2. Add Babel plugin
+
+**babel.config.js:**
+```js
+module.exports = {
+  presets: ['...'],
+  plugins: [
+    ['@idealyst/config/plugin', {
+      extends: ['../shared/.env'],
+      envPath: '.env'
+    }]
+  ]
 }
 ```
 
-### 3. Initialize and use
+### 3. Use in your app
 
 ```typescript
-// In your app entry point (e.g., App.tsx, main.tsx)
-import { setConfig } from '@idealyst/config'
-import { generatedConfig } from './config.generated'
-
-setConfig(generatedConfig)
-```
-
-```typescript
-// Anywhere in your app
 import { config } from '@idealyst/config'
 
+// Values are injected at build time!
 const apiUrl = config.get('API_URL')
 const analyticsEnabled = config.get('ANALYTICS_ENABLED') === 'true'
 ```
 
-## CLI Reference
+That's it! The Babel plugin reads your .env files at compile time and injects the values automatically.
 
-```bash
-idealyst-config generate [options]
+## Babel Plugin Options
 
-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
-```
+```js
+['@idealyst/config/plugin', {
+  // Inherit from these .env files (lowest to highest priority)
+  extends: ['../shared/.env', '../common/.env'],
 
-### Examples
+  // Main .env file (highest priority, default: auto-detect)
+  envPath: '.env',
 
-```bash
-# Simple - auto-detect .env
-idealyst-config generate
+  // Project root (default: process.cwd())
+  root: '/path/to/project'
+}]
+```
 
-# 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 +114,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 +204,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).
+## Type Generation (Optional)
 
-```typescript
-import { setConfig } from '@idealyst/config'
-import { generatedConfig } from './config.generated'
+For TypeScript autocomplete, generate type declarations:
 
-setConfig(generatedConfig)
-```
-
-## React Native Setup
-
-1. Install react-native-config:
 ```bash
-npm install react-native-config
-cd ios && pod install
+npx idealyst-config generate --extends ../shared/.env --env .env --types-only
 ```
 
-2. Follow [react-native-config setup](https://github.com/luggit/react-native-config#setup)
-
-3. Generate and use the same way as web:
-```bash
-idealyst-config generate --extends ../shared/.env --env .env
-```
-
-## 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 +224,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.14",
   "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,233 @@
+/**
+ * @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'
+ *     }]
+ *   ]
+ * }
+ * ```
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * 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 = []
+
+  // 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))
+      }
+    }
+  } else {
+    // Auto-detect shared env
+    const sharedEnv = findSharedEnv(projectRoot)
+    if (sharedEnv) {
+      configs.push(parseEnvFile(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))
+  }
+
+  // Merge configs (later configs override earlier ones)
+  return Object.assign({}, ...configs)
+}
+
+/**
+ * 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()
+
+  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)
+          if (!configCache.has(projectRoot)) {
+            configCache.set(projectRoot, loadConfig(opts, projectRoot))
+          }
+          const 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