@idealyst/config 1.2.14 → 1.2.16

package/README.md

@@ -91,11 +91,49 @@ That's it! The Babel plugin reads your .env files at compile time and injects th
   // Main .env file (highest priority, default: auto-detect)
   envPath: '.env',
 
+  // 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'
 }]
 ```
 
+### Build-time Validation
+
+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
+  }]
+]
+```
+
+**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.
+```
+
+**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.
+
+Error: @idealyst/config: Missing required config keys: JWT_SECRET
+```
+
 ### Auto-detection
 
 If you don't specify options, the plugin will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/config",
-  "version": "1.2.14",
+  "version": "1.2.16",
   "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/plugin.js

@@ -9,7 +9,9 @@
  *   plugins: [
  *     ['@idealyst/config/plugin', {
  *       extends: ['../shared/.env'],
- *       envPath: '.env'
+ *       envPath: '.env',
+ *       required: ['API_URL', 'AUTH_SECRET'],  // Warn if missing
+ *       errorOnMissing: true                    // Fail build if missing
  *     }]
  *   ]
  * }
@@ -19,6 +21,9 @@
 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.
  */
@@ -99,6 +104,7 @@ function findSharedEnv(directory) {
  */
 function loadConfig(options, projectRoot) {
   const configs = []
+  const sources = []
 
   // Load inherited configs first (lowest priority)
   if (options.extends) {
@@ -109,6 +115,7 @@ function loadConfig(options, projectRoot) {
 
       if (fs.existsSync(resolvedPath)) {
         configs.push(parseEnvFile(resolvedPath))
+        sources.push(resolvedPath)
       }
     }
   } else {
@@ -116,6 +123,7 @@ function loadConfig(options, projectRoot) {
     const sharedEnv = findSharedEnv(projectRoot)
     if (sharedEnv) {
       configs.push(parseEnvFile(sharedEnv))
+      sources.push(sharedEnv)
     }
   }
 
@@ -131,10 +139,44 @@ function loadConfig(options, projectRoot) {
 
   if (envPath && fs.existsSync(envPath)) {
     configs.push(parseEnvFile(envPath))
+    sources.push(envPath)
   }
 
   // Merge configs (later configs override earlier ones)
-  return Object.assign({}, ...configs)
+  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
 }
 
 /**
@@ -146,6 +188,9 @@ module.exports = function babelPluginIdealystConfig(babel) {
   // Cache config per project root
   const configCache = new Map()
 
+  // Reset validation state on new compilation
+  hasValidated = false
+
   return {
     name: '@idealyst/config',
 
@@ -156,10 +201,24 @@ module.exports = function babelPluginIdealystConfig(babel) {
           const projectRoot = opts.root || state.cwd || process.cwd()
 
           // Load config (cached per project root)
+          let configValues
           if (!configCache.has(projectRoot)) {
-            configCache.set(projectRoot, loadConfig(opts, 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)
           }
-          const configValues = configCache.get(projectRoot)
 
           // Track if this file imports from @idealyst/config
           let hasConfigImport = false
@@ -231,3 +290,4 @@ 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'