@eventuras/app-config 0.1.4

package/README.md

@@ -0,0 +1,423 @@
+# @eventuras/app-config
+
+Declarative environment configuration for Eventuras applications.
+
+## Overview
+
+`@eventuras/app-config` provides a centralized, type-safe way to manage environment variables across all Eventuras applications. Instead of manually validating env vars in code, you declare them in an `app.config.json` file.
+
+
+## Development
+
+```bash
+# Build the library
+pnpm build
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+```
+
+## TypeScript Type Generation
+
+The library includes a tool to generate TypeScript type definitions from your `app.config.json` file. This ensures your client-side environment variables are properly typed.
+
+### Using the generator programmatically
+
+Create a script in your app's `scripts/` directory:
+
+```typescript
+#!/usr/bin/env tsx
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { generateTypes } from '@eventuras/app-config/generator';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+generateTypes({
+  configPath: path.join(__dirname, '..', 'app.config.json'),
+  outputPath: path.join(__dirname, '..', 'src', 'config.client.generated.d.ts'),
+  interfaceName: 'WebPublicEnv', // Optional, defaults to 'PublicEnv'
+}).catch((error: unknown) => {
+  console.error('❌ Failed to generate types:', error);
+  process.exit(1);
+});
+```
+
+Add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "generate:config-types": "tsx scripts/generate-config-types.ts"
+  }
+}
+```
+
+### Generated output
+
+For example, given this config:
+
+```json
+{
+  "env": {
+    "NEXT_PUBLIC_API_BASE_URL": {
+      "required": true,
+      "client": true,
+      "type": "url",
+      "description": "API base URL"
+    },
+    "NEXT_PUBLIC_ORGANIZATION_ID": {
+      "required": false,
+      "client": true,
+      "type": "int",
+      "description": "Organization ID"
+    }
+  }
+}
+```
+
+The generated `config.client.generated.d.ts` will be:
+
+```typescript
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated from app.config.json
+ *
+ * To regenerate, run: pnpm generate:config-types
+ */
+
+export interface WebPublicEnv {
+  NEXT_PUBLIC_API_BASE_URL: string;
+  NEXT_PUBLIC_ORGANIZATION_ID?: number;
+}
+```
+
+You can then use this interface to type your client-side environment:
+
+```typescript
+import type { WebPublicEnv } from './config.client.generated';
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv extends WebPublicEnv {}
+  }
+}
+```
+
+
+## Installation
+
+```bash
+pnpm add @eventuras/app-config
+```
+
+## Usage
+
+### 1. Create `app.config.json`
+
+Create an `app.config.json` file in your app's root directory:
+
+```json
+{
+  "$schema": "https://eventuras.dev/schema/app-config.schema.json",
+  "name": "@eventuras/web",
+  "type": "app",
+  "description": "Main web frontend for Eventuras",
+  "env": {
+    "NEXT_PUBLIC_API_BASE_URL": {
+      "required": true,
+      "client": true,
+      "type": "url",
+      "description": "Base URL for the Eventuras API"
+    },
+    "NEXT_PUBLIC_ORGANIZATION_ID": {
+      "required": false,
+      "client": true,
+      "type": "string",
+      "description": "Organization ID for scoping configuration",
+      "default": "1"
+    },
+    "AUTH0_CLIENT_SECRET": {
+      "required": true,
+      "client": false,
+      "type": "string",
+      "description": "Auth0 client secret (server-side only)"
+    },
+    "PORT": {
+      "required": false,
+      "client": false,
+      "type": "int",
+      "description": "Port to run the server on",
+      "default": 3000
+    }
+  }
+}
+```
+
+### 2. Load and validate configuration
+
+#### Server-Side Usage (Recommended)
+
+```typescript
+import { createConfig } from '@eventuras/app-config';
+
+const config = createConfig('./app.config.json');
+
+// Method 1: Direct property access (cleanest for server-side)
+const clientId = config.env.AUTH0_CLIENT_ID;
+const clientSecret = config.env.AUTH0_CLIENT_SECRET;
+const sessionSecret = config.env.SESSION_SECRET;
+
+// Method 2: Using get() with type parameter
+const apiUrl = config.get<string>('NEXT_PUBLIC_API_BASE_URL');
+const orgId = config.get<string>('NEXT_PUBLIC_ORGANIZATION_ID');
+```
+
+#### Next.js Usage (Client + Server)
+
+For Next.js apps, use the `createEnvironment()` helper for automatic compatibility:
+
+```typescript
+// config.ts
+import { createConfig, createEnvironment } from '@eventuras/app-config';
+import { resolve } from 'path';
+
+// Server-side configuration
+export const appConfig = createConfig(
+  resolve(process.cwd(), 'app.config.json')
+);
+
+// Client-side public environment variables
+export const publicEnv = createEnvironment(
+  resolve(process.cwd(), 'app.config.json')
+);
+```
+
+```typescript
+// In client components - use publicEnv
+'use client';
+
+export default function MyComponent() {
+  const apiUrl = publicEnv.NEXT_PUBLIC_API_BASE_URL; // ✅ Works in client
+  const domain = publicEnv.NEXT_PUBLIC_AUTH0_DOMAIN;  // ✅ Works in client
+  
+  return <div>API: {apiUrl}</div>;
+}
+```
+
+```typescript
+// In server components / API routes - use appConfig.env
+export async function getServerSideProps() {
+  // Recommended: Use appConfig.env for server-side variables
+  const clientSecret = appConfig.env.AUTH0_CLIENT_SECRET;
+  const sessionSecret = appConfig.env.SESSION_SECRET;
+  
+  // Alternative: Use publicEnv.get() (also works server-side)
+  const altSecret = publicEnv.get('AUTH0_CLIENT_SECRET');
+  
+  return { props: {} };
+}
+```
+
+**Why explicit getters for NEXT_PUBLIC_*?**  
+Next.js performs build-time replacement of `process.env.NEXT_PUBLIC_*`. The `createEnvironment()` helper automatically generates getters that access `process.env` directly, ensuring client-side compatibility while still validating all variables server-side.
+
+### 3. Validation happens automatically
+
+When you create a config, all environment variables are validated:
+
+```typescript
+// This will throw if any required env vars are missing or invalid
+const config = createConfig('./app.config.json');
+```
+
+You can also validate explicitly during app initialization:
+
+```typescript
+import { validate } from '@eventuras/app-config';
+
+// In your app initialization (e.g., layout.tsx or main.ts)
+validate('./app.config.json');
+console.log('✓ Environment validated successfully');
+```
+
+Error messages are helpful:
+
+```
+Environment validation failed:
+
+❌ Required environment variable "NEXT_PUBLIC_API_BASE_URL" is not set.
+Description: Base URL for the Eventuras API
+
+❌ Environment variable "PORT" must be a valid integer.
+Got: "not-a-number"
+```
+
+## Environment Variable Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Any string value | `"hello"` |
+| `url` | Valid URL | `"https://api.example.com"` |
+| `int` | Integer number | `3000` |
+| `bool` | Boolean (true/false, 1/0) | `true`, `"1"` |
+| `json` | Valid JSON | `{"key": "value"}` |
+
+## Configuration Schema
+
+### `app.config.json` Structure
+
+```typescript
+interface AppConfig {
+  $schema?: string;          // JSON Schema reference
+  name: string;              // Package name (e.g., "@eventuras/web")
+  type: 'app';               // Always "app"
+  description?: string;      // Human-readable description
+  env: {                     // Environment variable definitions
+    [varName: string]: {
+      required: boolean;     // Is this var required?
+      client: boolean;       // Exposed to client? (NEXT_PUBLIC_*)
+      type: EnvVarType;      // 'string' | 'url' | 'int' | 'bool' | 'json'
+      description: string;   // What is this var for?
+      default?: any;         // Default value
+      pattern?: string;      // Regex pattern
+      enum?: string[];       // Allowed values
+    }
+  };
+  build?: {                  // Build configuration (optional)
+    outDir?: string;
+    target?: string;
+  };
+  runtime?: {                // Runtime configuration (optional)
+    port?: number;
+  };
+}
+```
+
+### Environment Variable Definition
+
+```typescript
+interface EnvVarDefinition {
+  required: boolean;         // Throw error if missing?
+  client: boolean;           // Client-side accessible?
+  type: EnvVarType;         // Expected type
+  description: string;       // Documentation
+  default?: any;            // Fallback value
+  pattern?: string;         // Validation regex
+  enum?: string[];          // Allowed values
+}
+```
+
+## Migration from `Environment.ts`
+
+### Before (apps/web/src/utils/Environment.ts)
+
+```typescript
+export enum EnvironmentVariables {
+  NEXT_PUBLIC_API_BASE_URL = 'NEXT_PUBLIC_API_BASE_URL',
+  AUTH0_CLIENT_SECRET = 'AUTH0_CLIENT_SECRET',
+}
+
+class Environment {
+  static validate() { /* ... */ }
+  
+  static get NEXT_PUBLIC_API_BASE_URL() {
+    return process.env.NEXT_PUBLIC_API_BASE_URL!;
+  }
+  
+  static get(identifier: string): string {
+    return process.env[identifier]!;
+  }
+}
+```
+
+### After (apps/web/app.config.json + config.ts)
+
+**app.config.json:**
+```json
+{
+  "name": "@eventuras/web",
+  "type": "app",
+  "env": {
+    "NEXT_PUBLIC_API_BASE_URL": {
+      "required": true,
+      "client": true,
+      "type": "url",
+      "description": "API base URL"
+    },
+    "AUTH0_CLIENT_SECRET": {
+      "required": true,
+      "client": false,
+      "type": "string",
+      "description": "Auth0 secret"
+    }
+  }
+}
+```
+
+**src/config.ts:**
+```typescript
+import { createConfig } from '@eventuras/app-config';
+
+export const config = createConfig('./app.config.json');
+
+// Usage:
+const apiUrl = config.get<string>('NEXT_PUBLIC_API_BASE_URL');
+const secret = config.get<string>('AUTH0_CLIENT_SECRET');
+```
+
+## Next.js Integration
+
+For Next.js apps, you can validate the config in your root layout:
+
+```typescript
+// app/layout.tsx
+import { validate } from '@eventuras/app-config';
+
+// Validate on server startup
+validate('./app.config.json');
+
+export default function RootLayout({ children }) {
+  return <html><body>{children}</body></html>;
+}
+```
+
+Or use the config instance directly:
+
+```typescript
+// app/layout.tsx
+import { createConfig } from '@eventuras/app-config';
+
+// Validate on startup
+const config = createConfig('./app.config.json');
+
+export default function RootLayout({ children }) {
+  return <html><body>{children}</body></html>;
+}
+```
+
+Access client-side variables (NEXT_PUBLIC_*):
+```typescript
+// Client component
+'use client';
+
+import { config } from '@/config';
+
+export function MyComponent() {
+  // ⚠️ IMPORTANT: For Next.js, NEXT_PUBLIC_* vars MUST access process.env directly
+  // Next.js replaces process.env.NEXT_PUBLIC_* at build time
+  const apiUrl = process.env.NEXT_PUBLIC_API_BASE_URL;
+  
+  // Or use the Environment wrapper which does this for you:
+  import { Environment } from '@/config';
+  const apiUrl = Environment.NEXT_PUBLIC_API_BASE_URL;
+  
+  return <div>API: {apiUrl}</div>;
+}
+```
+
+**Why the limitation?** Next.js performs build-time replacement of `process.env.NEXT_PUBLIC_*` variables. The `appConfig.get()` method reads from a runtime object, so it won't work for client-side code. Server-side code can use either approach.

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * CLI tool to generate TypeScript types from app.config.json
+ * Usage: node cli.js <configPath> <outputPath> [interfaceName]
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { generateTypes } from "./generator.js";
+//#region src/cli.ts
+/**
+* CLI tool to generate TypeScript types from app.config.json
+* Usage: node cli.js <configPath> <outputPath> [interfaceName]
+*/
+async function main() {
+	const [, , configPath, outputPath, interfaceName] = process.argv;
+	if (!configPath || !outputPath) {
+		console.error("Usage: generate-config-types <configPath> <outputPath> [interfaceName]");
+		console.error("Example: generate-config-types ./app.config.json ./src/config.generated.d.ts PublicEnv");
+		process.exit(1);
+	}
+	try {
+		await generateTypes({
+			configPath,
+			outputPath,
+			interfaceName
+		});
+	} catch (error) {
+		console.error("❌ Failed to generate types:", error);
+		process.exit(1);
+	}
+}
+main();
+//#endregion
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * CLI tool to generate TypeScript types from app.config.json\n * Usage: node cli.js <configPath> <outputPath> [interfaceName]\n */\n\nimport { generateTypes } from './generator.js';\n\nasync function main() {\n  const [, , configPath, outputPath, interfaceName] = process.argv;\n\n  if (!configPath || !outputPath) {\n    console.error('Usage: generate-config-types <configPath> <outputPath> [interfaceName]');\n    console.error('Example: generate-config-types ./app.config.json ./src/config.generated.d.ts PublicEnv');\n    process.exit(1);\n  }\n\n  try {\n    await generateTypes({\n      configPath,\n      outputPath,\n      interfaceName,\n    });\n  } catch (error) {\n    console.error('❌ Failed to generate types:', error);\n    process.exit(1);\n  }\n}\n\nmain();\n"],"mappings":";;;;;;;AAQA,eAAe,OAAO;CACpB,MAAM,KAAK,YAAY,YAAY,iBAAiB,QAAQ;CAE5D,IAAI,CAAC,cAAc,CAAC,YAAY;EAC9B,QAAQ,MAAM,wEAAwE;EACtF,QAAQ,MAAM,wFAAwF;EACtG,QAAQ,KAAK,CAAC;CAChB;CAEA,IAAI;EACF,MAAM,cAAc;GAClB;GACA;GACA;EACF,CAAC;CACH,SAAS,OAAO;EACd,QAAQ,MAAM,+BAA+B,KAAK;EAClD,QAAQ,KAAK,CAAC;CAChB;AACF;AAEA,KAAK"}

package/dist/clientside.d.ts

@@ -0,0 +1,97 @@
+import { AppConfig } from './types.js';
+export type { AppConfig } from './types.js';
+/**
+ * Map environment variable type string to TypeScript type
+ */
+type EnvVarTypeMap = {
+    string: string;
+    url: string;
+    int: number;
+    bool: boolean;
+    json: unknown;
+};
+/**
+ * Infer the TypeScript type from an environment variable definition with literal type support
+ */
+type InferEnvVarType<T> = T extends {
+    type: infer Type;
+    required: infer Req;
+} ? Type extends keyof EnvVarTypeMap ? Req extends true ? EnvVarTypeMap[Type] : EnvVarTypeMap[Type] | undefined : unknown : unknown;
+/**
+ * Extract public environment variable types from AppConfig
+ */
+export type PublicEnvObject<T> = T extends {
+    env: infer Env;
+} ? {
+    [K in keyof Env as Env[K] extends {
+        client: true;
+    } ? K : never]: InferEnvVarType<Env[K]>;
+} : never;
+/**
+ * Helper to parse integer value
+ */
+export declare function parseIntValue(value: string | undefined): number | undefined;
+/**
+ * Helper to parse boolean value
+ */
+export declare function parseBoolValue(value: string | undefined): boolean | undefined;
+/**
+ * Helper to parse JSON value
+ */
+export declare function parseJsonValue(value: string | undefined): unknown;
+/**
+ * Helper to define a getter property on an object.
+ *
+ * This is useful for creating explicit getters that Next.js can statically analyze.
+ * Instead of dynamic property access like process.env[varName], you should use
+ * direct property access like process.env.NEXT_PUBLIC_MY_VAR in the getter function.
+ *
+ * @param target - The target object to add the getter to
+ * @param propName - The property name
+ * @param getter - The getter function that returns the value
+ *
+ * @example
+ * ```ts
+ * const env = {};
+ * defineGetter(env, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+ * defineGetter(env, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+ * ```
+ */
+export declare function defineGetter<T>(target: Record<string, unknown>, propName: string, getter: () => T): void;
+/**
+ * Create an empty object for public environment variables.
+ *
+ * Use this with defineGetter to create explicit getters for NEXT_PUBLIC_* variables.
+ * This approach allows Next.js to perform static analysis and replace environment
+ * variables at build time.
+ *
+ * @returns An empty object to add getters to
+ *
+ * @example
+ * ```ts
+ * const publicEnv = createPublicEnvGetters();
+ * defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+ * defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+ * ```
+ */
+export declare function createPublicEnvGetters(): Record<string, unknown>;
+/**
+ * Create a public environment object with the correct TypeScript type.
+ *
+ * This is a type-safe wrapper that returns an empty object you can add getters to.
+ * Use this with defineGetter to create explicit NEXT_PUBLIC_* getters.
+ *
+ * @param _config - Plain app configuration object (used only for type inference)
+ * @returns An empty object with the correct TypeScript type for your config
+ *
+ * @example
+ * ```ts
+ * import appConfig from '../app.config.json';
+ *
+ * export const publicEnv = createPublicEnv(appConfig as AppConfig);
+ * defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+ * defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+ * ```
+ */
+export declare function createPublicEnv<const T extends AppConfig>(_config: T): PublicEnvObject<T>;
+//# sourceMappingURL=clientside.d.ts.map

package/dist/clientside.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientside.d.ts","sourceRoot":"","sources":["../src/clientside.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,KAAK,eAAe,CAAC,CAAC,IACpB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,CAAA;CAAE,GAC/C,IAAI,SAAS,MAAM,aAAa,GAC9B,GAAG,SAAS,IAAI,GACd,aAAa,CAAC,IAAI,CAAC,GACnB,aAAa,CAAC,IAAI,CAAC,GAAG,SAAS,GACjC,OAAO,GACT,OAAO,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,GAAG,CAAA;CAAE,GACzD;KACG,CAAC,IAAI,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,GAAG,CAAC,GAAG,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACzF,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAG7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,GACd,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAEzF"}

package/dist/clientside.js

@@ -0,0 +1,94 @@
+//#region src/clientside.ts
+/**
+* Helper to parse integer value
+*/
+function parseIntValue(value) {
+	if (value === void 0) return void 0;
+	return Number.parseInt(value, 10);
+}
+/**
+* Helper to parse boolean value
+*/
+function parseBoolValue(value) {
+	if (value === void 0) return void 0;
+	return value === "true" || value === "1";
+}
+/**
+* Helper to parse JSON value
+*/
+function parseJsonValue(value) {
+	if (value === void 0) return void 0;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}
+/**
+* Helper to define a getter property on an object.
+*
+* This is useful for creating explicit getters that Next.js can statically analyze.
+* Instead of dynamic property access like process.env[varName], you should use
+* direct property access like process.env.NEXT_PUBLIC_MY_VAR in the getter function.
+*
+* @param target - The target object to add the getter to
+* @param propName - The property name
+* @param getter - The getter function that returns the value
+*
+* @example
+* ```ts
+* const env = {};
+* defineGetter(env, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+* defineGetter(env, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+* ```
+*/
+function defineGetter(target, propName, getter) {
+	Object.defineProperty(target, propName, {
+		get: getter,
+		enumerable: true
+	});
+}
+/**
+* Create an empty object for public environment variables.
+*
+* Use this with defineGetter to create explicit getters for NEXT_PUBLIC_* variables.
+* This approach allows Next.js to perform static analysis and replace environment
+* variables at build time.
+*
+* @returns An empty object to add getters to
+*
+* @example
+* ```ts
+* const publicEnv = createPublicEnvGetters();
+* defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+* defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+* ```
+*/
+function createPublicEnvGetters() {
+	return {};
+}
+/**
+* Create a public environment object with the correct TypeScript type.
+*
+* This is a type-safe wrapper that returns an empty object you can add getters to.
+* Use this with defineGetter to create explicit NEXT_PUBLIC_* getters.
+*
+* @param _config - Plain app configuration object (used only for type inference)
+* @returns An empty object with the correct TypeScript type for your config
+*
+* @example
+* ```ts
+* import appConfig from '../app.config.json';
+*
+* export const publicEnv = createPublicEnv(appConfig as AppConfig);
+* defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);
+* defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));
+* ```
+*/
+function createPublicEnv(_config) {
+	return createPublicEnvGetters();
+}
+//#endregion
+export { createPublicEnv, createPublicEnvGetters, defineGetter, parseBoolValue, parseIntValue, parseJsonValue };
+
+//# sourceMappingURL=clientside.js.map

package/dist/clientside.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientside.js","names":[],"sources":["../src/clientside.ts"],"sourcesContent":["import { AppConfig } from './types.js';\n\n// Re-export types for client usage\nexport type { AppConfig } from './types.js';\n\n/**\n * Map environment variable type string to TypeScript type\n */\ntype EnvVarTypeMap = {\n  string: string;\n  url: string;\n  int: number;\n  bool: boolean;\n  json: unknown;\n};\n\n/**\n * Infer the TypeScript type from an environment variable definition with literal type support\n */\ntype InferEnvVarType<T> =\n  T extends { type: infer Type; required: infer Req }\n    ? Type extends keyof EnvVarTypeMap\n      ? Req extends true\n        ? EnvVarTypeMap[Type]\n        : EnvVarTypeMap[Type] | undefined\n      : unknown\n    : unknown;\n\n/**\n * Extract public environment variable types from AppConfig\n */\nexport type PublicEnvObject<T> = T extends { env: infer Env }\n  ? {\n      [K in keyof Env as Env[K] extends { client: true } ? K : never]: InferEnvVarType<Env[K]>;\n    }\n  : never;\n\n/**\n * Helper to parse integer value\n */\nexport function parseIntValue(value: string | undefined): number | undefined {\n  if (value === undefined) return undefined;\n  return Number.parseInt(value, 10);\n}\n\n/**\n * Helper to parse boolean value\n */\nexport function parseBoolValue(value: string | undefined): boolean | undefined {\n  if (value === undefined) return undefined;\n  return value === 'true' || value === '1';\n}\n\n/**\n * Helper to parse JSON value\n */\nexport function parseJsonValue(value: string | undefined): unknown {\n  if (value === undefined) return undefined;\n  try {\n    return JSON.parse(value);\n  } catch {\n    return value;\n  }\n}\n\n/**\n * Helper to define a getter property on an object.\n *\n * This is useful for creating explicit getters that Next.js can statically analyze.\n * Instead of dynamic property access like process.env[varName], you should use\n * direct property access like process.env.NEXT_PUBLIC_MY_VAR in the getter function.\n *\n * @param target - The target object to add the getter to\n * @param propName - The property name\n * @param getter - The getter function that returns the value\n *\n * @example\n * ```ts\n * const env = {};\n * defineGetter(env, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);\n * defineGetter(env, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));\n * ```\n */\nexport function defineGetter<T>(\n  target: Record<string, unknown>,\n  propName: string,\n  getter: () => T\n): void {\n  Object.defineProperty(target, propName, {\n    get: getter,\n    enumerable: true,\n  });\n}\n\n/**\n * Create an empty object for public environment variables.\n *\n * Use this with defineGetter to create explicit getters for NEXT_PUBLIC_* variables.\n * This approach allows Next.js to perform static analysis and replace environment\n * variables at build time.\n *\n * @returns An empty object to add getters to\n *\n * @example\n * ```ts\n * const publicEnv = createPublicEnvGetters();\n * defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);\n * defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));\n * ```\n */\nexport function createPublicEnvGetters(): Record<string, unknown> {\n  return {};\n}\n\n/**\n * Create a public environment object with the correct TypeScript type.\n *\n * This is a type-safe wrapper that returns an empty object you can add getters to.\n * Use this with defineGetter to create explicit NEXT_PUBLIC_* getters.\n *\n * @param _config - Plain app configuration object (used only for type inference)\n * @returns An empty object with the correct TypeScript type for your config\n *\n * @example\n * ```ts\n * import appConfig from '../app.config.json';\n *\n * export const publicEnv = createPublicEnv(appConfig as AppConfig);\n * defineGetter(publicEnv, 'NEXT_PUBLIC_API_URL', () => process.env.NEXT_PUBLIC_API_URL);\n * defineGetter(publicEnv, 'NEXT_PUBLIC_ORG_ID', () => parseIntValue(process.env.NEXT_PUBLIC_ORG_ID));\n * ```\n */\nexport function createPublicEnv<const T extends AppConfig>(_config: T): PublicEnvObject<T> {\n  return createPublicEnvGetters() as PublicEnvObject<T>;\n}\n"],"mappings":";;;;AAwCA,SAAgB,cAAc,OAA+C;CAC3E,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;CAChC,OAAO,OAAO,SAAS,OAAO,EAAE;AAClC;;;;AAKA,SAAgB,eAAe,OAAgD;CAC7E,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;CAChC,OAAO,UAAU,UAAU,UAAU;AACvC;;;;AAKA,SAAgB,eAAe,OAAoC;CACjE,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;CAChC,IAAI;EACF,OAAO,KAAK,MAAM,KAAK;CACzB,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,aACd,QACA,UACA,QACM;CACN,OAAO,eAAe,QAAQ,UAAU;EACtC,KAAK;EACL,YAAY;CACd,CAAC;AACH;;;;;;;;;;;;;;;;;AAkBA,SAAgB,yBAAkD;CAChE,OAAO,CAAC;AACV;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,gBAA2C,SAAgC;CACzF,OAAO,uBAAuB;AAChC"}

package/dist/generator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate TypeScript types from app.config.json
+ * This module provides functions to generate type definitions from configuration files
+ */
+export interface GenerateTypesOptions {
+    /** Path to app.config.json file */
+    configPath: string;
+    /** Path where the generated .d.ts file should be written */
+    outputPath: string;
+    /** Name of the interface to generate (default: 'PublicEnv') */
+    interfaceName?: string;
+}
+/**
+ * Generate TypeScript type definitions from an app.config.json file
+ * @param options - Configuration options for type generation
+ */
+export declare function generateTypes(options: GenerateTypesOptions): Promise<void>;
+//# sourceMappingURL=generator.d.ts.map