@idealyst/config 1.2.12 → 1.2.14

package/README.md

@@ -1,14 +1,14 @@
 # @idealyst/config
 
-Cross-platform configuration and environment variable support for React and React Native applications.
+Cross-platform configuration for React and React Native with env inheritance support.
 
 ## Features
 
 - **Single API** - Same code works on web and native
-- **Type-safe** - Auto-generated TypeScript declarations for autocomplete
-- **Prefix abstraction** - Use canonical names (`API_URL`), web implementation handles `VITE_` prefix internally
-- **Validation** - Check required config at app startup
-- **Zero runtime dependencies** - Uses platform-native solutions
+- **Env inheritance** - Shared config with platform-specific overrides
+- **Babel plugin** - Config injected at build time, no runtime overhead
+- **Type-safe** - Auto-generated TypeScript declarations
+- **Monorepo friendly** - Designed for shared/web/mobile patterns
 
 ## Installation
 
@@ -22,89 +22,148 @@ cd ios && pod install
 
 ## Quick Start
 
-```typescript
-import { config } from '@idealyst/config'
-
-// Get a config value
-const apiUrl = config.get('API_URL')
-
-// Get with default value
-const port = config.get('PORT', '3000')
-
-// Get required value (throws if missing)
-const secret = config.getRequired('JWT_SECRET')
+### 1. Create your .env files
 
-// Validate required vars at startup
-config.validate(['API_URL', 'AUTH_SECRET'])
+```
+my-app/
+├── packages/
+│   ├── shared/
+│   │   └── .env          # Base config (lowest priority)
+│   ├── web/
+│   │   └── .env          # Web overrides
+│   └── mobile/
+│       └── .env          # Mobile overrides
 ```
 
-## Environment Files
-
-### React Native (.env)
-
+**shared/.env:**
 ```bash
-# No prefix needed
 API_URL=https://api.example.com
 GOOGLE_CLIENT_ID=abc123
-JWT_SECRET=supersecret
+ANALYTICS_ENABLED=true
 ```
 
-### Vite Web (.env)
+**web/.env:**
+```bash
+# Override API for web
+API_URL=https://web-api.example.com
+```
 
+**mobile/.env:**
 ```bash
-# Must use VITE_ prefix for client exposure
-VITE_API_URL=https://api.example.com
-VITE_GOOGLE_CLIENT_ID=abc123
-VITE_JWT_SECRET=supersecret
+# Mobile uses shared API_URL, but different analytics
+ANALYTICS_ENABLED=false
 ```
 
-**Important:** Your code always uses canonical names without the `VITE_` prefix. The web implementation handles this internally:
+### 2. Add Babel plugin
+
+**babel.config.js:**
+```js
+module.exports = {
+  presets: ['...'],
+  plugins: [
+    ['@idealyst/config/plugin', {
+      extends: ['../shared/.env'],
+      envPath: '.env'
+    }]
+  ]
+}
+```
+
+### 3. Use in your app
 
 ```typescript
-// Both platforms - same code
+import { config } from '@idealyst/config'
+
+// Values are injected at build time!
 const apiUrl = config.get('API_URL')
+const analyticsEnabled = config.get('ANALYTICS_ENABLED') === 'true'
 ```
 
-## Type Generation
+That's it! The Babel plugin reads your .env files at compile time and injects the values automatically.
 
-Generate TypeScript declarations for autocomplete support:
+## Babel Plugin Options
 
-```bash
-# Auto-detect .env file
-npx idealyst-config generate
+```js
+['@idealyst/config/plugin', {
+  // Inherit from these .env files (lowest to highest priority)
+  extends: ['../shared/.env', '../common/.env'],
 
-# Specify .env file
-npx idealyst-config generate --env .env.local
+  // Main .env file (highest priority, default: auto-detect)
+  envPath: '.env',
 
-# Custom output path
-npx idealyst-config generate --output types/env.d.ts
+  // Project root (default: process.cwd())
+  root: '/path/to/project'
+}]
 ```
 
-This creates a declaration file that provides autocomplete for your config keys:
+### Auto-detection
 
-```typescript
-// Generated: src/env.d.ts
-declare module '@idealyst/config' {
-  interface ConfigKeys {
-    API_URL: string
-    GOOGLE_CLIENT_ID: string
-    JWT_SECRET: string
-  }
-}
+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
+
+```js
+// Minimal config - auto-detects everything
+plugins: [
+  '@idealyst/config/plugin'
+]
+```
+
+## Inheritance Priority
+
+Configs are merged in order, with later files overriding earlier ones:
+
+```
+1. extends[0]: ../shared/.env     (lowest priority)
+2. extends[1]: ../common/.env
+3. envPath: .env                  (highest priority)
 ```
 
-Now you get autocomplete when calling `config.get()`:
+## Vite Setup
+
+For Vite projects, add to `vite.config.ts`:
 
 ```typescript
-config.get('API_URL')  // Autocomplete shows available keys
-config.get('INVALID')  // TypeScript error - key not in ConfigKeys
+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
 
 ### `config.get(key: string): string | undefined`
 
-Get a configuration value by key.
+Get a config value.
 
 ```typescript
 const apiUrl = config.get('API_URL')
@@ -112,7 +171,7 @@ const apiUrl = config.get('API_URL')
 
 ### `config.get(key: string, defaultValue: string): string`
 
-Get a configuration value with a fallback default.
+Get with fallback default.
 
 ```typescript
 const port = config.get('PORT', '3000')
@@ -120,16 +179,15 @@ const port = config.get('PORT', '3000')
 
 ### `config.getRequired(key: string): string`
 
-Get a required configuration value. Throws an error if not defined.
+Get required value. Throws if not defined.
 
 ```typescript
 const secret = config.getRequired('JWT_SECRET')
-// Throws: 'Required config key "JWT_SECRET" is not defined'
 ```
 
 ### `config.has(key: string): boolean`
 
-Check if a configuration key exists.
+Check if key exists.
 
 ```typescript
 if (config.has('DEBUG')) {
@@ -137,54 +195,76 @@ if (config.has('DEBUG')) {
 }
 ```
 
-### `config.keys(): string[]`
+### `config.validate(requiredKeys: string[]): void`
 
-Get all available configuration keys.
+Validate required keys at startup.
 
 ```typescript
-console.log('Available config:', config.keys())
+config.validate(['API_URL', 'AUTH_SECRET'])
+// Throws ConfigValidationError if any are missing
 ```
 
-### `config.validate(requiredKeys: string[]): void`
+## Type Generation (Optional)
+
+For TypeScript autocomplete, generate type declarations:
 
-Validate that all required keys are present. Throws `ConfigValidationError` if any are missing.
+```bash
+npx idealyst-config generate --extends ../shared/.env --env .env --types-only
+```
+
+This creates `src/config.generated.d.ts`:
 
 ```typescript
-// At app startup
-try {
-  config.validate(['API_URL', 'AUTH_SECRET', 'DATABASE_URL'])
-} catch (error) {
-  if (error instanceof ConfigValidationError) {
-    console.error('Missing config:', error.missingKeys)
+declare module '@idealyst/config' {
+  interface ConfigKeys {
+    API_URL: string
+    GOOGLE_CLIENT_ID: string
+    ANALYTICS_ENABLED: string
   }
 }
 ```
 
-## Platform Implementation Details
+Add to your build script for automatic updates:
 
-### Web (Vite)
+```json
+{
+  "scripts": {
+    "prebuild": "idealyst-config generate --extends ../shared/.env --types-only"
+  }
+}
+```
 
-Uses `import.meta.env` with automatic `VITE_` prefix handling:
-- Your code: `config.get('API_URL')`
-- Internal lookup: `import.meta.env.VITE_API_URL`
+## How It Works
 
-### React Native
+The Babel plugin transforms your code at compile time:
 
-Uses `react-native-config` for native environment variable injection:
-- Your code: `config.get('API_URL')`
-- Internal lookup: `Config.API_URL`
+**Input:**
+```typescript
+import { config } from '@idealyst/config'
 
-Make sure to follow [react-native-config setup](https://github.com/luggit/react-native-config#setup) for your platform.
+const apiUrl = config.get('API_URL')
+```
 
-## Best Practices
+**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" })
 
-1. **Generate types after .env changes** - Run `idealyst-config generate` whenever you add/remove environment variables
+const apiUrl = config.get('API_URL')
+```
 
-2. **Validate at startup** - Call `config.validate()` early in your app to catch missing config
+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
 
-3. **Use .env.example** - Commit an example file with all required keys (no values)
+## Best Practices
 
-4. **Don't commit secrets** - Add `.env` and `.env.local` to `.gitignore`
+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/bin/idealyst-config.js

@@ -1,60 +1,93 @@
 #!/usr/bin/env node
 
 /**
- * CLI for @idealyst/config - Generate TypeScript types from .env files
+ * CLI for @idealyst/config - Generate config from .env files with inheritance
  *
- * This is a self-contained JavaScript CLI that doesn't require TypeScript
- * compilation at runtime. It implements the same logic as src/cli/generate.ts.
+ * Supports monorepo patterns with shared config:
+ *   shared/.env      → base config (lowest priority)
+ *   web/.env         → web overrides
+ *   mobile/.env      → mobile overrides
  */
 
 const fs = require('fs')
 const path = require('path')
 
 /**
- * Parse a .env file and extract all key names.
- * Strips VITE_ prefix to normalize to canonical names.
+ * Parse a .env file and extract key-value pairs.
  */
-function parseEnvFile(content) {
-  const keys = []
+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()
 
-    // Skip empty lines and comments
     if (!trimmed || trimmed.startsWith('#')) {
       continue
     }
 
-    // Extract key name (everything before the first =)
     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 to canonical names
+    // Strip VITE_ prefix to normalize
     if (key.startsWith('VITE_')) {
       key = key.substring(5)
     }
 
-    // Only add unique keys
-    if (key && !keys.includes(key)) {
-      keys.push(key)
-    }
+    config[key] = value
   }
 
-  return keys.sort()
+  return config
 }
 
 /**
- * Generate TypeScript declaration content from a list of config keys.
+ * Generate TypeScript config module with actual values.
  */
-function generateDeclaration(keys, sourceFile) {
+function generateConfigModule(config, sourceFiles) {
+  const sources = sourceFiles.join(', ')
+  const entries = Object.entries(config)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`)
+    .join(',\n')
+
+  return `// Auto-generated by @idealyst/config - DO NOT EDIT
+// Sources: ${sources}
+// Run \`idealyst-config generate\` to regenerate
+
+/**
+ * Generated configuration values.
+ * Merged from: ${sources}
+ */
+export const generatedConfig: Record<string, string> = {
+${entries}
+}
+`
+}
+
+/**
+ * Generate TypeScript declaration file.
+ */
+function generateDeclaration(keys, sourceFiles) {
   const keyDefinitions = keys.map(k => `    ${k}: string`).join('\n')
+  const sources = sourceFiles.join(', ')
 
   return `// Auto-generated by @idealyst/config - DO NOT EDIT
-// Generated from: ${sourceFile}
+// Sources: ${sources}
 // Run \`idealyst-config generate\` to regenerate
 
 declare module '@idealyst/config' {
@@ -76,42 +109,78 @@ export {}
 }
 
 /**
- * Find the most appropriate .env file in a directory.
+ * 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',
+    '../.env.shared',
+  ]
+  for (const pattern of patterns) {
+    const sharedPath = path.resolve(directory, pattern)
+    if (fs.existsSync(sharedPath)) {
+      return sharedPath
+    }
+  }
   return null
 }
 
 function printUsage() {
   console.log(`
-@idealyst/config - Generate TypeScript types from .env files
+@idealyst/config - Generate config from .env files with inheritance
 
 Usage:
   idealyst-config generate [options]
 
 Options:
-  --env <path>      Path to .env file (default: auto-detect)
-  --output <path>   Output path for .d.ts file (default: src/env.d.ts)
-  --help            Show this help message
+  --env <path>        Path to .env file (default: auto-detect)
+  --extends <path>    Inherit from another .env file (can use multiple times)
+  --output <path>     Output path for generated config (default: src/config.generated.ts)
+  --types-only        Generate only .d.ts file, no values
+  --help              Show this help message
 
 Examples:
+  # Simple usage - auto-detect .env
   idealyst-config generate
-  idealyst-config generate --env .env.local
-  idealyst-config generate --env .env --output types/env.d.ts
+
+  # With shared config inheritance
+  idealyst-config generate --extends ../shared/.env --env .env
+
+  # Multiple inheritance (lowest to highest priority)
+  idealyst-config generate --extends ../../shared/.env --extends ../.env.common --env .env
+
+  # Types only (for type checking without exposing values)
+  idealyst-config generate --types-only --output src/env.d.ts
+
+Inheritance:
+  In a monorepo with shared/web/mobile packages, you can set up inheritance:
+
+  shared/.env     → API_URL=https://api.example.com
+  web/.env        → API_URL=https://web-api.example.com (overrides shared)
+  mobile/.env     → (inherits API_URL from shared)
+
+  The --extends flag loads configs in order, with later files taking priority.
 `)
 }
 
 function parseArgs(args) {
-  const result = {}
+  const result = { extends: [] }
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
@@ -120,8 +189,12 @@ function parseArgs(args) {
       result.help = true
     } else if (arg === '--env' && args[i + 1]) {
       result.env = args[++i]
+    } else if (arg === '--extends' && args[i + 1]) {
+      result.extends.push(args[++i])
     } else if (arg === '--output' && args[i + 1]) {
       result.output = args[++i]
+    } else if (arg === '--types-only') {
+      result.typesOnly = true
     } else if (!arg.startsWith('-') && !result.command) {
       result.command = arg
     }
@@ -145,59 +218,91 @@ function main() {
   }
 
   const cwd = process.cwd()
+  const sourceFiles = []
+  const configs = []
+
+  // Load inherited configs first (lowest priority)
+  for (const extendPath of args.extends) {
+    const resolvedPath = path.isAbsolute(extendPath)
+      ? extendPath
+      : path.resolve(cwd, extendPath)
+
+    if (fs.existsSync(resolvedPath)) {
+      configs.push(parseEnvFile(resolvedPath))
+      sourceFiles.push(path.relative(cwd, resolvedPath))
+      console.log(`  ← ${path.relative(cwd, resolvedPath)}`)
+    } else {
+      console.warn(`Warning: Inherited env file not found: ${resolvedPath}`)
+    }
+  }
 
-  // Find or use the specified .env file
+  // Auto-detect shared env if no extends specified
+  if (args.extends.length === 0) {
+    const sharedEnv = findSharedEnv(cwd)
+    if (sharedEnv) {
+      configs.push(parseEnvFile(sharedEnv))
+      sourceFiles.push(path.relative(cwd, sharedEnv))
+      console.log(`  ← ${path.relative(cwd, sharedEnv)} (auto-detected shared)`)
+    }
+  }
+
+  // Load main env file (highest priority)
   let envPath
   if (args.env) {
-    envPath = path.isAbsolute(args.env) ? args.env : path.join(cwd, args.env)
+    envPath = path.isAbsolute(args.env) ? args.env : path.resolve(cwd, args.env)
   } else {
     envPath = findEnvFile(cwd)
-    if (!envPath) {
-      console.error('Error: No .env file found in current directory.')
-      console.error('Create a .env file or specify one with --env <path>')
-      process.exit(1)
-    }
   }
 
-  // Check if env file exists
-  if (!fs.existsSync(envPath)) {
-    console.error(`Error: Environment file not found: ${envPath}`)
+  if (envPath && fs.existsSync(envPath)) {
+    configs.push(parseEnvFile(envPath))
+    sourceFiles.push(path.relative(cwd, envPath))
+    console.log(`  ← ${path.relative(cwd, envPath)}`)
+  } else if (args.env) {
+    console.error(`Error: Environment file not found: ${args.env}`)
     process.exit(1)
   }
 
-  // Determine output path
-  const outputPath = args.output
-    ? (path.isAbsolute(args.output) ? args.output : path.join(cwd, args.output))
-    : path.join(cwd, 'src', 'env.d.ts')
-
-  try {
-    // Read and parse env file
-    const envContent = fs.readFileSync(envPath, 'utf-8')
-    const keys = parseEnvFile(envContent)
+  if (configs.length === 0) {
+    console.error('Error: No .env files found.')
+    console.error('Create a .env file or specify one with --env <path>')
+    process.exit(1)
+  }
 
-    if (keys.length === 0) {
-      console.warn('Warning: No environment variables found in', envPath)
-    }
+  // Merge configs (later configs override earlier ones)
+  const mergedConfig = Object.assign({}, ...configs)
+  const keys = Object.keys(mergedConfig).sort()
 
-    // Generate declaration
-    const declaration = generateDeclaration(keys, path.basename(envPath))
+  // Determine output path
+  const outputPath = args.output
+    ? (path.isAbsolute(args.output) ? args.output : path.resolve(cwd, args.output))
+    : path.resolve(cwd, 'src', 'config.generated.ts')
 
-    // Ensure output directory exists
-    const outputDir = path.dirname(outputPath)
-    if (!fs.existsSync(outputDir)) {
-      fs.mkdirSync(outputDir, { recursive: true })
-    }
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath)
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true })
+  }
 
-    // Write declaration file
+  if (args.typesOnly) {
+    // Generate declaration file only
+    const declaration = generateDeclaration(keys, sourceFiles)
     fs.writeFileSync(outputPath, declaration)
-
-    console.log(`Generated config types at: ${outputPath}`)
-    console.log(`Source: ${envPath}`)
-    console.log(`Keys: ${keys.join(', ')}`)
-  } catch (error) {
-    console.error('Error generating config types:', error.message)
-    process.exit(1)
+    console.log(`\nGenerated types at: ${path.relative(cwd, outputPath)}`)
+  } else {
+    // Generate config module
+    const module = generateConfigModule(mergedConfig, sourceFiles)
+    fs.writeFileSync(outputPath, module)
+    console.log(`\nGenerated config at: ${path.relative(cwd, outputPath)}`)
+
+    // Also generate declaration file
+    const declPath = outputPath.replace(/\.ts$/, '.d.ts')
+    const declaration = generateDeclaration(keys, sourceFiles)
+    fs.writeFileSync(declPath, declaration)
+    console.log(`Generated types at: ${path.relative(cwd, declPath)}`)
   }
+
+  console.log(`Keys: ${keys.join(', ')}`)
 }
 
 main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/config",
-  "version": "1.2.12",
+  "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

package/src/cli/generate.ts

@@ -3,22 +3,38 @@ import path from 'path'
 
 export interface GenerateOptions {
   /**
-   * Path to the .env file to read
+   * Path to the platform-specific .env file (highest priority)
    */
-  envPath: string
+  envPath?: string
 
   /**
-   * Path to write the generated TypeScript declaration file
+   * Paths to inherited .env files (lowest to highest priority)
+   * e.g., ['../shared/.env'] - shared is loaded first, then envPath overrides
+   */
+  inheritFrom?: string[]
+
+  /**
+   * Path to write the generated TypeScript config file
    */
   outputPath: string
+
+  /**
+   * Whether to generate types only (declaration file) or full config module
+   */
+  typesOnly?: boolean
 }
 
 /**
- * Parse a .env file and extract all key names.
+ * Parse a .env file and extract key-value pairs.
  * Strips VITE_ prefix to normalize to canonical names.
  */
-export function parseEnvFile(content: string): string[] {
-  const keys: string[] = []
+export function parseEnvFile(filePath: string): Record<string, string> {
+  if (!fs.existsSync(filePath)) {
+    return {}
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8')
+  const config: Record<string, string> = {}
 
   for (const line of content.split('\n')) {
     const trimmed = line.trim()
@@ -28,36 +44,48 @@ export function parseEnvFile(content: string): string[] {
       continue
     }
 
-    // Extract key name (everything before the first =)
+    // Extract key=value
     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 to canonical names
     if (key.startsWith('VITE_')) {
       key = key.substring(5)
     }
 
-    // Only add unique keys
-    if (key && !keys.includes(key)) {
-      keys.push(key)
-    }
+    config[key] = value
   }
 
-  return keys.sort()
+  return config
 }
 
 /**
- * Generate TypeScript declaration content from a list of config keys.
+ * Merge multiple env configs with later configs taking priority.
  */
-export function generateDeclaration(keys: string[], sourceFile: string): string {
+export function mergeEnvConfigs(...configs: Record<string, string>[]): Record<string, string> {
+  return Object.assign({}, ...configs)
+}
+
+/**
+ * Generate TypeScript declaration content from config keys.
+ */
+export function generateDeclaration(keys: string[], sourceFiles: string[]): string {
   const keyDefinitions = keys.map(k => `    ${k}: string`).join('\n')
+  const sources = sourceFiles.join(', ')
 
   return `// Auto-generated by @idealyst/config - DO NOT EDIT
-// Generated from: ${sourceFile}
+// Sources: ${sources}
 // Run \`idealyst-config generate\` to regenerate
 
 declare module '@idealyst/config' {
@@ -79,42 +107,98 @@ export {}
 }
 
 /**
- * Generate TypeScript config types from an .env file.
- *
- * @param options - Generation options
- * @returns The path to the generated file
+ * Generate a TypeScript config module with actual values.
  */
-export function generateConfigTypes(options: GenerateOptions): string {
-  // Read the .env file
-  if (!fs.existsSync(options.envPath)) {
-    throw new Error(`Environment file not found: ${options.envPath}`)
+export function generateConfigModule(config: Record<string, string>, sourceFiles: string[]): string {
+  const sources = sourceFiles.join(', ')
+  const entries = Object.entries(config)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`)
+    .join(',\n')
+
+  return `// Auto-generated by @idealyst/config - DO NOT EDIT
+// Sources: ${sources}
+// Run \`idealyst-config generate\` to regenerate
+
+/**
+ * Generated configuration values.
+ * Merged from: ${sources}
+ */
+export const generatedConfig: Record<string, string> = {
+${entries}
+}
+`
+}
+
+/**
+ * Generate config from .env files with inheritance support.
+ */
+export function generateConfigTypes(options: GenerateOptions): { outputPath: string; keys: string[] } {
+  const sourceFiles: string[] = []
+  const configs: Record<string, string>[] = []
+
+  // Load inherited configs first (lowest priority)
+  if (options.inheritFrom) {
+    for (const inheritPath of options.inheritFrom) {
+      const resolvedPath = path.isAbsolute(inheritPath)
+        ? inheritPath
+        : path.resolve(path.dirname(options.outputPath), inheritPath)
+
+      if (fs.existsSync(resolvedPath)) {
+        configs.push(parseEnvFile(resolvedPath))
+        sourceFiles.push(path.basename(resolvedPath))
+      }
+    }
   }
 
-  const envContent = fs.readFileSync(options.envPath, 'utf-8')
-  const keys = parseEnvFile(envContent)
+  // Load main env file (highest priority)
+  if (options.envPath) {
+    const resolvedEnvPath = path.isAbsolute(options.envPath)
+      ? options.envPath
+      : path.resolve(process.cwd(), options.envPath)
 
-  if (keys.length === 0) {
-    console.warn('Warning: No environment variables found in', options.envPath)
+    if (fs.existsSync(resolvedEnvPath)) {
+      configs.push(parseEnvFile(resolvedEnvPath))
+      sourceFiles.push(path.basename(resolvedEnvPath))
+    }
   }
 
-  // Generate the declaration content
-  const declaration = generateDeclaration(keys, path.basename(options.envPath))
+  // Merge configs
+  const mergedConfig = mergeEnvConfigs(...configs)
+  const keys = Object.keys(mergedConfig).sort()
+
+  if (keys.length === 0) {
+    console.warn('Warning: No environment variables found')
+  }
 
-  // Ensure the output directory exists
+  // Ensure output directory exists
   const outputDir = path.dirname(options.outputPath)
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true })
   }
 
-  // Write the declaration file
-  fs.writeFileSync(options.outputPath, declaration)
+  if (options.typesOnly) {
+    // Generate declaration file only
+    const declaration = generateDeclaration(keys, sourceFiles)
+    fs.writeFileSync(options.outputPath, declaration)
+  } else {
+    // Generate full config module
+    const module = generateConfigModule(mergedConfig, sourceFiles)
+    fs.writeFileSync(options.outputPath, module)
+
+    // Also generate declaration file alongside
+    const declPath = options.outputPath.replace(/\.ts$/, '.d.ts')
+    if (declPath !== options.outputPath) {
+      const declaration = generateDeclaration(keys, sourceFiles)
+      fs.writeFileSync(declPath, declaration)
+    }
+  }
 
-  return options.outputPath
+  return { outputPath: options.outputPath, keys }
 }
 
 /**
  * Find the most appropriate .env file in a directory.
- * Prefers .env.local > .env.development > .env
  */
 export function findEnvFile(directory: string): string | null {
   const candidates = ['.env.local', '.env.development', '.env']
@@ -128,3 +212,25 @@ export function findEnvFile(directory: string): string | null {
 
   return null
 }
+
+/**
+ * Look for a shared .env file in parent directories.
+ */
+export function findSharedEnv(directory: string): string | null {
+  // Common patterns for shared env in monorepos
+  const patterns = [
+    '../shared/.env',
+    '../../shared/.env',
+    '../.env.shared',
+    '../../.env.shared',
+  ]
+
+  for (const pattern of patterns) {
+    const sharedPath = path.resolve(directory, pattern)
+    if (fs.existsSync(sharedPath)) {
+      return sharedPath
+    }
+  }
+
+  return null
+}

package/src/config.web.ts

@@ -2,22 +2,63 @@ import type { IConfig } from './types'
 import { ConfigValidationError } from './types'
 
 /**
- * Web implementation of IConfig using Vite's import.meta.env.
+ * Config store - populated by the generated config module or manually via setConfig().
+ */
+let configStore: Record<string, string> = {}
+
+/**
+ * Set config values. Called automatically when importing from a project that
+ * has generated config, or can be called manually.
+ *
+ * @example
+ * ```typescript
+ * // In your app entry point:
+ * import { setConfig } from '@idealyst/config'
+ * import { generatedConfig } from './config.generated'
+ *
+ * setConfig(generatedConfig)
+ * ```
+ */
+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 }
+}
+
+/**
+ * Web implementation of IConfig.
+ *
+ * Config values come from:
+ * 1. Generated config module (via setConfig)
+ * 2. Manual setConfig() calls
+ *
+ * Usage:
+ * ```typescript
+ * import { config, setConfig } from '@idealyst/config'
+ * import { generatedConfig } from './config.generated'
  *
- * This implementation automatically handles the VITE_ prefix:
- * - User code uses canonical names: config.get('API_URL')
- * - Internally we look up: import.meta.env.VITE_API_URL
+ * // Initialize config (do this once at app startup)
+ * setConfig(generatedConfig)
  *
- * This allows the same code to work on both web and native platforms.
+ * // Then use anywhere
+ * const apiUrl = config.get('API_URL')
+ * ```
  */
 class WebConfig implements IConfig {
   get(key: string, defaultValue?: string): string | undefined {
-    // Always use VITE_ prefix - this is the Vite convention for exposing
-    // environment variables to client-side code.
-    // User code uses canonical names: config.get('API_URL')
-    // Internally we look up: import.meta.env.VITE_API_URL
-    const value = (import.meta.env as Record<string, string | undefined>)[`VITE_${key}`]
-    return value ?? defaultValue
+    return configStore[key] ?? defaultValue
   }
 
   getRequired(key: string): string {
@@ -25,21 +66,18 @@ class WebConfig implements IConfig {
     if (value === undefined) {
       throw new Error(
         `Required config key "${key}" is not defined. ` +
-        `Make sure VITE_${key} is set in your .env file.`
+        `Make sure you've run "idealyst-config generate" and imported the generated config.`
       )
     }
     return value
   }
 
   has(key: string): boolean {
-    return (import.meta.env as Record<string, string | undefined>)[`VITE_${key}`] !== undefined
+    return configStore[key] !== undefined
   }
 
   keys(): string[] {
-    // Return canonical names (strip VITE_ prefix)
-    return Object.keys(import.meta.env)
-      .filter(k => k.startsWith('VITE_'))
-      .map(k => k.replace(/^VITE_/, ''))
+    return Object.keys(configStore).sort()
   }
 
   validate(requiredKeys: string[]): void {

package/src/index.web.ts

@@ -1,24 +1,29 @@
 /**
  * Web entry point for @idealyst/config
  *
- * Uses Vite's import.meta.env for environment variable access.
- * The VITE_ prefix is handled automatically - use canonical names in your code.
+ * Config values come from a generated module created by the CLI.
+ * This approach works with any bundler and supports env inheritance.
  *
  * @example
  * ```typescript
- * import { config } from '@idealyst/config'
+ * // 1. Generate config (run in terminal)
+ * // idealyst-config generate --extends ../shared/.env --env .env
  *
- * // In your .env file: VITE_API_URL=https://api.example.com
- * // In your code: use canonical name without prefix
+ * // 2. Initialize in your app entry point
+ * import { config, setConfig } from '@idealyst/config'
+ * import { generatedConfig } from './config.generated'
+ * setConfig(generatedConfig)
+ *
+ * // 3. Use anywhere
  * const apiUrl = config.get('API_URL')
  * ```
  */
 
-import WebConfig from './config.web'
+import WebConfig, { setConfig, clearConfig, getConfigStore } from './config.web'
 
 // Create singleton instance for web
 const config = new WebConfig()
 
 export default config
-export { config, config as Config, WebConfig }
+export { config, config as Config, WebConfig, setConfig, clearConfig, getConfigStore }
 export * from './types'

package/src/vite-env.d.ts

@@ -1,22 +0,0 @@
-/// <reference types="vite/client" />
-
-/**
- * Type declarations for Vite's import.meta.env
- *
- * This file provides type information for import.meta.env when Vite types
- * are not available. In projects using Vite, these types are provided by
- * vite/client.
- */
-
-interface ImportMetaEnv {
-  [key: string]: string | undefined
-  readonly MODE: string
-  readonly BASE_URL: string
-  readonly PROD: boolean
-  readonly DEV: boolean
-  readonly SSR: boolean
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv
-}