@idealyst/config 1.2.12 → 1.2.13

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
+- **Type-safe** - Auto-generated TypeScript declarations
+- **Bundler agnostic** - No bundler configuration needed
+- **Monorepo friendly** - Designed for shared/web/mobile patterns
 
 ## Installation
 
@@ -22,89 +22,124 @@ cd ios && pod install
 
 ## Quick Start
 
-```typescript
-import { config } from '@idealyst/config'
+### 1. Create your .env files
 
-// Get a config value
-const apiUrl = config.get('API_URL')
-
-// Get with default value
-const port = config.get('PORT', '3000')
+```
+my-app/
+├── packages/
+│   ├── shared/
+│   │   └── .env          # Base config (lowest priority)
+│   ├── web/
+│   │   └── .env          # Web overrides
+│   └── mobile/
+│       └── .env          # Mobile overrides
+```
 
-// Get required value (throws if missing)
-const secret = config.getRequired('JWT_SECRET')
+**shared/.env:**
+```bash
+API_URL=https://api.example.com
+GOOGLE_CLIENT_ID=abc123
+ANALYTICS_ENABLED=true
+```
 
-// Validate required vars at startup
-config.validate(['API_URL', 'AUTH_SECRET'])
+**web/.env:**
+```bash
+# Override API for web
+API_URL=https://web-api.example.com
 ```
 
-## Environment Files
+**mobile/.env:**
+```bash
+# Mobile uses shared API_URL, but different analytics
+ANALYTICS_ENABLED=false
+```
 
-### React Native (.env)
+### 2. Generate config
 
 ```bash
-# No prefix needed
-API_URL=https://api.example.com
-GOOGLE_CLIENT_ID=abc123
-JWT_SECRET=supersecret
+# In packages/web/
+npx idealyst-config generate --extends ../shared/.env --env .env
+
+# In packages/mobile/
+npx idealyst-config generate --extends ../shared/.env --env .env
 ```
 
-### Vite Web (.env)
+This creates `src/config.generated.ts` with merged values:
 
-```bash
-# Must use VITE_ prefix for client exposure
-VITE_API_URL=https://api.example.com
-VITE_GOOGLE_CLIENT_ID=abc123
-VITE_JWT_SECRET=supersecret
+```typescript
+// Web: API_URL overridden, others inherited
+export const generatedConfig = {
+  API_URL: "https://web-api.example.com",
+  GOOGLE_CLIENT_ID: "abc123",
+  ANALYTICS_ENABLED: "true"
+}
 ```
 
-**Important:** Your code always uses canonical names without the `VITE_` prefix. The web implementation handles this internally:
+### 3. Initialize and use
 
 ```typescript
-// Both platforms - same code
-const apiUrl = config.get('API_URL')
+// In your app entry point (e.g., App.tsx, main.tsx)
+import { setConfig } from '@idealyst/config'
+import { generatedConfig } from './config.generated'
+
+setConfig(generatedConfig)
 ```
 
-## Type Generation
+```typescript
+// Anywhere in your app
+import { config } from '@idealyst/config'
 
-Generate TypeScript declarations for autocomplete support:
+const apiUrl = config.get('API_URL')
+const analyticsEnabled = config.get('ANALYTICS_ENABLED') === 'true'
+```
+
+## CLI Reference
 
 ```bash
-# Auto-detect .env file
-npx idealyst-config generate
+idealyst-config generate [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
+```
 
-# Specify .env file
-npx idealyst-config generate --env .env.local
+### Examples
 
-# Custom output path
-npx idealyst-config generate --output types/env.d.ts
-```
+```bash
+# Simple - auto-detect .env
+idealyst-config generate
 
-This creates a declaration file that provides autocomplete for your config keys:
+# With shared inheritance
+idealyst-config generate --extends ../shared/.env --env .env
 
-```typescript
-// Generated: src/env.d.ts
-declare module '@idealyst/config' {
-  interface ConfigKeys {
-    API_URL: string
-    GOOGLE_CLIENT_ID: string
-    JWT_SECRET: string
-  }
-}
+# Multiple inheritance (lowest to highest priority)
+idealyst-config generate \
+  --extends ../../shared/.env \
+  --extends ../.env.common \
+  --env .env
+
+# Types only (for CI/type checking without values)
+idealyst-config generate --types-only --output src/env.d.ts
 ```
 
-Now you get autocomplete when calling `config.get()`:
+## Inheritance Priority
+
+Configs are merged in order, with later files overriding earlier ones:
 
-```typescript
-config.get('API_URL')  // Autocomplete shows available keys
-config.get('INVALID')  // TypeScript error - key not in ConfigKeys
+```
+1. --extends ../shared/.env     (lowest priority)
+2. --extends ../.env.common
+3. --env .env                   (highest priority)
 ```
 
 ## 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 +147,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 +155,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 +171,77 @@ 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`
+### `setConfig(config: Record<string, string>)`
 
-Validate that all required keys are present. Throws `ConfigValidationError` if any are missing.
+Initialize config values (call once at app startup).
 
 ```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)
-  }
-}
+import { setConfig } from '@idealyst/config'
+import { generatedConfig } from './config.generated'
+
+setConfig(generatedConfig)
 ```
 
-## Platform Implementation Details
+## React Native Setup
 
-### Web (Vite)
+1. Install react-native-config:
+```bash
+npm install react-native-config
+cd ios && pod install
+```
 
-Uses `import.meta.env` with automatic `VITE_` prefix handling:
-- Your code: `config.get('API_URL')`
-- Internal lookup: `import.meta.env.VITE_API_URL`
+2. Follow [react-native-config setup](https://github.com/luggit/react-native-config#setup)
 
-### React Native
+3. Generate and use the same way as web:
+```bash
+idealyst-config generate --extends ../shared/.env --env .env
+```
 
-Uses `react-native-config` for native environment variable injection:
-- Your code: `config.get('API_URL')`
-- Internal lookup: `Config.API_URL`
+## Type Safety
 
-Make sure to follow [react-native-config setup](https://github.com/luggit/react-native-config#setup) for your platform.
+The CLI generates TypeScript declarations for autocomplete:
 
-## Best Practices
+```typescript
+// Generated: src/config.generated.d.ts
+declare module '@idealyst/config' {
+  interface ConfigKeys {
+    API_URL: string
+    GOOGLE_CLIENT_ID: string
+    ANALYTICS_ENABLED: string
+  }
+}
+```
+
+This provides autocomplete and catches typos at compile time.
+
+## Build Integration
 
-1. **Generate types after .env changes** - Run `idealyst-config generate` whenever you add/remove environment variables
+Add to your build scripts:
 
-2. **Validate at startup** - Call `config.validate()` early in your app to catch missing config
+```json
+{
+  "scripts": {
+    "prebuild": "idealyst-config generate --extends ../shared/.env",
+    "build": "vite build"
+  }
+}
+```
 
-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. **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
 
 ## 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.13",
   "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",

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
-}