@idealyst/config 1.2.12

package/README.md

@@ -0,0 +1,191 @@
+# @idealyst/config
+
+Cross-platform configuration and environment variable support for React and React Native applications.
+
+## 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
+
+## Installation
+
+```bash
+npm install @idealyst/config
+
+# For React Native, also install react-native-config
+npm install react-native-config
+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')
+
+// Validate required vars at startup
+config.validate(['API_URL', 'AUTH_SECRET'])
+```
+
+## Environment Files
+
+### React Native (.env)
+
+```bash
+# No prefix needed
+API_URL=https://api.example.com
+GOOGLE_CLIENT_ID=abc123
+JWT_SECRET=supersecret
+```
+
+### Vite Web (.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
+```
+
+**Important:** Your code always uses canonical names without the `VITE_` prefix. The web implementation handles this internally:
+
+```typescript
+// Both platforms - same code
+const apiUrl = config.get('API_URL')
+```
+
+## Type Generation
+
+Generate TypeScript declarations for autocomplete support:
+
+```bash
+# Auto-detect .env file
+npx idealyst-config generate
+
+# Specify .env file
+npx idealyst-config generate --env .env.local
+
+# Custom output path
+npx idealyst-config generate --output types/env.d.ts
+```
+
+This creates a declaration file that provides autocomplete for your config keys:
+
+```typescript
+// Generated: src/env.d.ts
+declare module '@idealyst/config' {
+  interface ConfigKeys {
+    API_URL: string
+    GOOGLE_CLIENT_ID: string
+    JWT_SECRET: string
+  }
+}
+```
+
+Now you get autocomplete when calling `config.get()`:
+
+```typescript
+config.get('API_URL')  // Autocomplete shows available keys
+config.get('INVALID')  // TypeScript error - key not in ConfigKeys
+```
+
+## API Reference
+
+### `config.get(key: string): string | undefined`
+
+Get a configuration value by key.
+
+```typescript
+const apiUrl = config.get('API_URL')
+```
+
+### `config.get(key: string, defaultValue: string): string`
+
+Get a configuration value with a fallback default.
+
+```typescript
+const port = config.get('PORT', '3000')
+```
+
+### `config.getRequired(key: string): string`
+
+Get a required configuration value. Throws an error 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.
+
+```typescript
+if (config.has('DEBUG')) {
+  enableDebugMode()
+}
+```
+
+### `config.keys(): string[]`
+
+Get all available configuration keys.
+
+```typescript
+console.log('Available config:', config.keys())
+```
+
+### `config.validate(requiredKeys: string[]): void`
+
+Validate that all required keys are present. Throws `ConfigValidationError` if any are missing.
+
+```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)
+  }
+}
+```
+
+## Platform Implementation Details
+
+### Web (Vite)
+
+Uses `import.meta.env` with automatic `VITE_` prefix handling:
+- Your code: `config.get('API_URL')`
+- Internal lookup: `import.meta.env.VITE_API_URL`
+
+### React Native
+
+Uses `react-native-config` for native environment variable injection:
+- Your code: `config.get('API_URL')`
+- Internal lookup: `Config.API_URL`
+
+Make sure to follow [react-native-config setup](https://github.com/luggit/react-native-config#setup) for your platform.
+
+## Best Practices
+
+1. **Generate types after .env changes** - Run `idealyst-config generate` whenever you add/remove environment variables
+
+2. **Validate at startup** - Call `config.validate()` early in your app to catch missing config
+
+3. **Use .env.example** - Commit an example file with all required keys (no values)
+
+4. **Don't commit secrets** - Add `.env` and `.env.local` to `.gitignore`
+
+## License
+
+MIT

package/bin/idealyst-config.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * CLI for @idealyst/config - Generate TypeScript types from .env files
+ *
+ * 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.
+ */
+
+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.
+ */
+function parseEnvFile(content) {
+  const keys = []
+
+  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()
+
+    // 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)
+    }
+  }
+
+  return keys.sort()
+}
+
+/**
+ * Generate TypeScript declaration content from a list of config keys.
+ */
+function generateDeclaration(keys, sourceFile) {
+  const keyDefinitions = keys.map(k => `    ${k}: string`).join('\n')
+
+  return `// Auto-generated by @idealyst/config - DO NOT EDIT
+// Generated from: ${sourceFile}
+// Run \`idealyst-config generate\` to regenerate
+
+declare module '@idealyst/config' {
+  interface ConfigKeys {
+${keyDefinitions}
+  }
+
+  interface IConfig {
+    get<K extends keyof ConfigKeys>(key: K): string | undefined
+    get<K extends keyof ConfigKeys>(key: K, defaultValue: string): string
+    getRequired<K extends keyof ConfigKeys>(key: K): string
+    has<K extends keyof ConfigKeys>(key: K): boolean
+    validate(requiredKeys: (keyof ConfigKeys)[]): void
+  }
+}
+
+export {}
+`
+}
+
+/**
+ * Find the most appropriate .env file in a 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
+}
+
+function printUsage() {
+  console.log(`
+@idealyst/config - Generate TypeScript types from .env files
+
+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
+
+Examples:
+  idealyst-config generate
+  idealyst-config generate --env .env.local
+  idealyst-config generate --env .env --output types/env.d.ts
+`)
+}
+
+function parseArgs(args) {
+  const result = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true
+    } else if (arg === '--env' && args[i + 1]) {
+      result.env = args[++i]
+    } else if (arg === '--output' && args[i + 1]) {
+      result.output = args[++i]
+    } else if (!arg.startsWith('-') && !result.command) {
+      result.command = arg
+    }
+  }
+
+  return result
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.help || (!args.command && process.argv.length <= 2)) {
+    printUsage()
+    process.exit(0)
+  }
+
+  if (args.command !== 'generate') {
+    console.error(`Unknown command: ${args.command}`)
+    console.error('Run "idealyst-config --help" for usage information.')
+    process.exit(1)
+  }
+
+  const cwd = process.cwd()
+
+  // Find or use the specified .env file
+  let envPath
+  if (args.env) {
+    envPath = path.isAbsolute(args.env) ? args.env : path.join(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}`)
+    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 (keys.length === 0) {
+      console.warn('Warning: No environment variables found in', envPath)
+    }
+
+    // Generate declaration
+    const declaration = generateDeclaration(keys, path.basename(envPath))
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputPath)
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true })
+    }
+
+    // Write declaration file
+    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)
+  }
+}
+
+main()

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@idealyst/config",
+  "version": "1.2.12",
+  "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",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "bin": {
+    "idealyst-config": "./bin/idealyst-config.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/config"
+  },
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": {
+        "types": "./src/index.web.ts",
+        "import": "./src/index.web.ts",
+        "require": "./src/index.web.ts"
+      },
+      "default": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "require": "./src/index.ts"
+      }
+    },
+    "./generate": {
+      "types": "./src/cli/generate.ts",
+      "import": "./src/cli/generate.ts",
+      "require": "./src/cli/generate.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "react-native-config": ">=1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-config": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "react-native-config": "^1.5.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "config",
+    "configuration",
+    "env",
+    "environment",
+    "dotenv",
+    "react",
+    "react-native",
+    "cross-platform",
+    "idealyst"
+  ]
+}

package/src/cli/generate.ts

@@ -0,0 +1,130 @@
+import fs from 'fs'
+import path from 'path'
+
+export interface GenerateOptions {
+  /**
+   * Path to the .env file to read
+   */
+  envPath: string
+
+  /**
+   * Path to write the generated TypeScript declaration file
+   */
+  outputPath: string
+}
+
+/**
+ * Parse a .env file and extract all key names.
+ * Strips VITE_ prefix to normalize to canonical names.
+ */
+export function parseEnvFile(content: string): string[] {
+  const keys: string[] = []
+
+  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()
+
+    // 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)
+    }
+  }
+
+  return keys.sort()
+}
+
+/**
+ * Generate TypeScript declaration content from a list of config keys.
+ */
+export function generateDeclaration(keys: string[], sourceFile: string): string {
+  const keyDefinitions = keys.map(k => `    ${k}: string`).join('\n')
+
+  return `// Auto-generated by @idealyst/config - DO NOT EDIT
+// Generated from: ${sourceFile}
+// Run \`idealyst-config generate\` to regenerate
+
+declare module '@idealyst/config' {
+  interface ConfigKeys {
+${keyDefinitions}
+  }
+
+  interface IConfig {
+    get<K extends keyof ConfigKeys>(key: K): string | undefined
+    get<K extends keyof ConfigKeys>(key: K, defaultValue: string): string
+    getRequired<K extends keyof ConfigKeys>(key: K): string
+    has<K extends keyof ConfigKeys>(key: K): boolean
+    validate(requiredKeys: (keyof ConfigKeys)[]): void
+  }
+}
+
+export {}
+`
+}
+
+/**
+ * Generate TypeScript config types from an .env file.
+ *
+ * @param options - Generation options
+ * @returns The path to the generated file
+ */
+export function generateConfigTypes(options: GenerateOptions): string {
+  // Read the .env file
+  if (!fs.existsSync(options.envPath)) {
+    throw new Error(`Environment file not found: ${options.envPath}`)
+  }
+
+  const envContent = fs.readFileSync(options.envPath, 'utf-8')
+  const keys = parseEnvFile(envContent)
+
+  if (keys.length === 0) {
+    console.warn('Warning: No environment variables found in', options.envPath)
+  }
+
+  // Generate the declaration content
+  const declaration = generateDeclaration(keys, path.basename(options.envPath))
+
+  // Ensure the 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)
+
+  return options.outputPath
+}
+
+/**
+ * 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']
+
+  for (const candidate of candidates) {
+    const envPath = path.join(directory, candidate)
+    if (fs.existsSync(envPath)) {
+      return envPath
+    }
+  }
+
+  return null
+}

package/src/cli/index.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+import path from 'path'
+import { generateConfigTypes, findEnvFile } from './generate'
+
+function printUsage(): void {
+  console.log(`
+@idealyst/config - Generate TypeScript types from .env files
+
+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
+
+Examples:
+  idealyst-config generate
+  idealyst-config generate --env .env.local
+  idealyst-config generate --env .env --output types/env.d.ts
+`)
+}
+
+function parseArgs(args: string[]): { command?: string; env?: string; output?: string; help?: boolean } {
+  const result: { command?: string; env?: string; output?: string; help?: boolean } = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true
+    } else if (arg === '--env' && args[i + 1]) {
+      result.env = args[++i]
+    } else if (arg === '--output' && args[i + 1]) {
+      result.output = args[++i]
+    } else if (!arg.startsWith('-') && !result.command) {
+      result.command = arg
+    }
+  }
+
+  return result
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.help || (!args.command && process.argv.length <= 2)) {
+    printUsage()
+    process.exit(0)
+  }
+
+  if (args.command !== 'generate') {
+    console.error(`Unknown command: ${args.command}`)
+    console.error('Run "idealyst-config --help" for usage information.')
+    process.exit(1)
+  }
+
+  const cwd = process.cwd()
+
+  // Find or use the specified .env file
+  let envPath: string
+  if (args.env) {
+    envPath = path.isAbsolute(args.env) ? args.env : path.join(cwd, args.env)
+  } else {
+    const foundEnv = findEnvFile(cwd)
+    if (!foundEnv) {
+      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)
+    }
+    envPath = foundEnv
+  }
+
+  // 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 {
+    const result = generateConfigTypes({
+      envPath,
+      outputPath,
+    })
+
+    console.log(`Generated config types at: ${result}`)
+    console.log(`Source: ${envPath}`)
+  } catch (error) {
+    console.error('Error generating config types:', (error as Error).message)
+    process.exit(1)
+  }
+}
+
+main()

package/src/config.native.ts

@@ -0,0 +1,60 @@
+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
+}
+
+/**
+ * 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.
+ *
+ * The .env file should use canonical names:
+ * API_URL=https://api.example.com
+ * GOOGLE_CLIENT_ID=abc123
+ */
+class NativeConfig implements IConfig {
+  get(key: string, defaultValue?: string): string | undefined {
+    return RNConfig[key] ?? defaultValue
+  }
+
+  getRequired(key: string): string {
+    const value = this.get(key)
+    if (value === undefined) {
+      throw new Error(
+        `Required config key "${key}" is not defined. ` +
+        `Make sure ${key} is set in your .env file.`
+      )
+    }
+    return value
+  }
+
+  has(key: string): boolean {
+    return RNConfig[key] !== undefined
+  }
+
+  keys(): string[] {
+    return Object.keys(RNConfig)
+  }
+
+  validate(requiredKeys: string[]): void {
+    const missing = requiredKeys.filter(key => !this.has(key))
+    if (missing.length > 0) {
+      throw new ConfigValidationError(missing)
+    }
+  }
+}
+
+export default NativeConfig
+export { NativeConfig }

package/src/config.web.ts

@@ -0,0 +1,54 @@
+import type { IConfig } from './types'
+import { ConfigValidationError } from './types'
+
+/**
+ * Web implementation of IConfig using Vite's import.meta.env.
+ *
+ * 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
+ *
+ * This allows the same code to work on both web and native platforms.
+ */
+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
+  }
+
+  getRequired(key: string): string {
+    const value = this.get(key)
+    if (value === undefined) {
+      throw new Error(
+        `Required config key "${key}" is not defined. ` +
+        `Make sure VITE_${key} is set in your .env file.`
+      )
+    }
+    return value
+  }
+
+  has(key: string): boolean {
+    return (import.meta.env as Record<string, string | undefined>)[`VITE_${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_/, ''))
+  }
+
+  validate(requiredKeys: string[]): void {
+    const missing = requiredKeys.filter(key => !this.has(key))
+    if (missing.length > 0) {
+      throw new ConfigValidationError(missing)
+    }
+  }
+}
+
+export default WebConfig
+export { WebConfig }

package/src/index.native.ts

@@ -0,0 +1,23 @@
+/**
+ * Native entry point for @idealyst/config
+ *
+ * Uses react-native-config for environment variable access.
+ * No prefix is required - use canonical names directly.
+ *
+ * @example
+ * ```typescript
+ * import { config } from '@idealyst/config'
+ *
+ * // In your .env file: API_URL=https://api.example.com
+ * const apiUrl = config.get('API_URL')
+ * ```
+ */
+
+import NativeConfig from './config.native'
+
+// Create singleton instance for native
+const config = new NativeConfig()
+
+export default config
+export { config, config as Config, NativeConfig }
+export * from './types'

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @idealyst/config - Cross-platform configuration for React and React Native
+ *
+ * This is the generic entry point that exports types and the base interface.
+ * Platform-specific entry points (index.web.ts, index.native.ts) export
+ * pre-configured instances for their respective platforms.
+ *
+ * @example
+ * ```typescript
+ * import { config } from '@idealyst/config'
+ *
+ * // Get a config value
+ * const apiUrl = config.get('API_URL')
+ *
+ * // Get with default
+ * const port = config.get('PORT', '3000')
+ *
+ * // Get required (throws if missing)
+ * const secret = config.getRequired('JWT_SECRET')
+ *
+ * // Validate at startup
+ * config.validate(['API_URL', 'JWT_SECRET'])
+ * ```
+ */
+
+export * from './types'
+export type { IConfig, ConfigKeys } from './types'
+export { ConfigValidationError } from './types'

package/src/index.web.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { config } from '@idealyst/config'
+ *
+ * // In your .env file: VITE_API_URL=https://api.example.com
+ * // In your code: use canonical name without prefix
+ * const apiUrl = config.get('API_URL')
+ * ```
+ */
+
+import WebConfig from './config.web'
+
+// Create singleton instance for web
+const config = new WebConfig()
+
+export default config
+export { config, config as Config, WebConfig }
+export * from './types'

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Base config interface for cross-platform configuration access.
+ * This interface can be augmented by generated types for autocomplete support.
+ */
+export interface IConfig {
+  /**
+   * Get a configuration value by key.
+   * @param key - The canonical key name (without VITE_ prefix)
+   * @param defaultValue - Optional default value if key is not set
+   * @returns The value, the default value, or undefined if not set
+   */
+  get(key: string, defaultValue?: string): string | undefined
+
+  /**
+   * Get a required configuration value. Throws if not set.
+   * @param key - The canonical key name (without VITE_ prefix)
+   * @returns The value
+   * @throws Error if the key is not defined
+   */
+  getRequired(key: string): string
+
+  /**
+   * Check if a configuration key exists.
+   * @param key - The canonical key name (without VITE_ prefix)
+   * @returns True if the key is defined
+   */
+  has(key: string): boolean
+
+  /**
+   * Get all available configuration keys.
+   * @returns Array of canonical key names
+   */
+  keys(): string[]
+
+  /**
+   * Validate that all required keys are present.
+   * @param requiredKeys - Array of required key names
+   * @throws ConfigValidationError if any keys are missing
+   */
+  validate(requiredKeys: string[]): void
+}
+
+/**
+ * Error thrown when required configuration keys are missing.
+ */
+export class ConfigValidationError extends Error {
+  /**
+   * The list of missing configuration keys.
+   */
+  public readonly missingKeys: string[]
+
+  constructor(missingKeys: string[]) {
+    super(`Missing required config keys: ${missingKeys.join(', ')}`)
+    this.name = 'ConfigValidationError'
+    this.missingKeys = missingKeys
+  }
+}
+
+/**
+ * Interface for ConfigKeys - augmented by generated types.
+ * When you run `idealyst-config generate`, this interface is extended
+ * with your actual environment variable keys.
+ */
+export interface ConfigKeys {
+  [key: string]: string
+}

package/src/vite-env.d.ts

@@ -0,0 +1,22 @@
+/// <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
+}