Package Exports

react-azure-config
react-azure-config/client
react-azure-config/client/insights
react-azure-config/server

Readme

🚀 react-azure-config

The Ultimate Multi-App Configuration Library! Solve React's build-time environment variable problem with enterprise-grade Azure integration and monorepo support.

Created by Jovani Samuels

🎯 The Problems This Solves

React apps traditionally bake environment variables into JavaScript bundles at build time:

❌ Different Docker images needed for each environment
❌ Cannot change configuration without rebuilding
❌ Secrets exposed in frontend code
❌ Complex CI/CD pipeline
❌ No support for monorepo multi-app configurations

✅ The Ultimate Solution

Load configuration at runtime with enterprise-grade multi-app support:

✅ Same Docker image works across all environments
✅ Multi-app monorepo with isolated configurations
✅ Environment variables loaded at runtime, not build time
✅ Per-app Azure App Configuration endpoints and authentication
✅ Smart environment variable parsing (REACT_APP_ADMIN_API_URL → Admin app gets API_URL)
✅ Intelligent multi-level caching with change detection
✅ Enterprise debugging tools and comprehensive monitoring
✅ No secrets baked into JavaScript bundles

🌟 New in v0.4.0: Multi-App Enterprise Features

Multi-App Environment Variable System

Transform app-specific environment variables automatically:

# Admin app variables
REACT_APP_ADMIN_API_URL=https://admin-api.com
REACT_APP_ADMIN_DB_HOST=admin-db.example.com

# Client app variables  
REACT_APP_CLIENT_API_URL=https://client-api.com
REACT_APP_CLIENT_AUTH_KEY=client-key-123

# Shared variables
REACT_APP_LOG_LEVEL=debug

Per-App Azure App Configuration

Each app gets its own Azure App Configuration instance:

# Azure endpoints per app
AZURE_APP_CONFIG_ENDPOINT_ADMIN=https://admin-config.azconfig.io
AZURE_APP_CONFIG_ENDPOINT_CLIENT=https://client-config.azconfig.io

# Per-app authentication
AZURE_CLIENT_ID_ADMIN=admin-client-id
AZURE_CLIENT_SECRET_ADMIN=admin-secret
AZURE_CLIENT_ID_CLIENT=client-client-id

Enterprise Configuration Precedence

Perfect priority chain for maximum flexibility:

Azure App Configuration (per app - highest priority)
App-specific env vars (REACT_APP_ADMIN_*)
Generic env vars (REACT_APP_*)
App-specific .env files (apps/admin/.env)
Root .env file (.env - lowest priority)

📦 Installation

npm install react-azure-config
# or
yarn add react-azure-config

🚀 Quick Start

Single App Usage (Backward Compatible)

import React from 'react';
import { ConfigProvider, useConfig, useConfigValue } from 'react-azure-config';

function App() {
  return (
    <ConfigProvider>
      <MyComponent />
    </ConfigProvider>
  );
}

function MyComponent() {
  const apiUrl = useConfigValue<string>('api.url', 'https://fallback-api.com');
  const appTitle = useConfigValue<string>('app.title', 'Default App');
  
  return (
    <div>
      <h1>{appTitle}</h1>
      <p>API URL: {apiUrl}</p>
    </div>
  );
}

Multi-App Monorepo Usage

import React from 'react';
import { ConfigProvider, useConfig } from 'react-azure-config';

// Admin App Component
function AdminApp() {
  return (
    <ConfigProvider appId="admin">
      {/* Gets: Azure config + REACT_APP_ADMIN_* + fallbacks */}
      <AdminDashboard />
    </ConfigProvider>
  );
}

// Client App Component  
function ClientApp() {
  return (
    <ConfigProvider appId="client">
      {/* Gets: Azure config + REACT_APP_CLIENT_* + fallbacks */}
      <ClientPortal />
    </ConfigProvider>
  );
}

function AdminDashboard() {
  const { data: config, loading, error } = useConfig();
  
  if (loading) return <div>Loading admin configuration...</div>;
  
  return (
    <div>
      <h1>Admin Dashboard</h1>
      <p>Admin API: {config?.api?.url}</p>
      <p>Admin DB: {config?.db?.host}</p>
    </div>
  );
}

🐳 Ultimate Docker Integration

Same Docker image, multiple apps, different configurations:

# Single command with multiple apps
docker run \
  -e AZURE_APP_CONFIG_ENDPOINT_ADMIN=https://admin-config.azconfig.io \
  -e AZURE_APP_CONFIG_ENDPOINT_CLIENT=https://client-config.azconfig.io \
  -e REACT_APP_ADMIN_API_URL=https://admin-api.com \
  -e REACT_APP_CLIENT_API_URL=https://client-api.com \
  -e REACT_APP_LOG_LEVEL=debug \
  my-monorepo-app

Docker Compose for Multi-App:

version: '3.8'
services:
  monorepo-app:
    image: my-monorepo-app:latest
    environment:
      # Azure App Configuration per app
      - AZURE_APP_CONFIG_ENDPOINT_ADMIN=https://admin-config.azconfig.io
      - AZURE_APP_CONFIG_ENDPOINT_CLIENT=https://client-config.azconfig.io
      
      # App-specific configurations
      - REACT_APP_ADMIN_API_URL=https://staging-admin-api.com
      - REACT_APP_ADMIN_DB_HOST=admin-staging-db.com
      - REACT_APP_CLIENT_API_URL=https://staging-client-api.com
      - REACT_APP_CLIENT_AUTH_KEY=staging-client-key
      
      # Shared configurations
      - REACT_APP_LOG_LEVEL=debug
      - REACT_APP_ENVIRONMENT=staging
    ports:
      - "3000:80"

🏗️ Project Structure for Monorepo

my-monorepo/
├── apps/
│   ├── admin/
│   │   └── .env                 # Admin-specific config (lowest priority)
│   ├── client/
│   │   └── .env                 # Client-specific config (lowest priority)
│   └── analytics/
│       └── .env                 # Analytics-specific config
├── .env                         # Shared root config (fallback)
├── src/
│   ├── AdminApp.tsx            # <ConfigProvider appId="admin" />
│   ├── ClientApp.tsx           # <ConfigProvider appId="client" />
│   └── AnalyticsApp.tsx        # <ConfigProvider appId="analytics" />
└── package.json

📊 Advanced Environment Variable Transformation

Smart parsing with nested structures:

# Environment Variables
REACT_APP_ADMIN_API_URL=https://admin-api.com
REACT_APP_ADMIN_DB__HOST=admin-db.com          # Double underscore = nested
REACT_APP_ADMIN_DB__PORT=5432
REACT_APP_ADMIN_FEATURES__DARK_MODE=true

REACT_APP_CLIENT_API_URL=https://client-api.com
REACT_APP_CLIENT_AUTH__TOKEN=client-token-123
REACT_APP_CLIENT_AUTH__TIMEOUT=30000

Admin app gets:

{
  "api": { "url": "https://admin-api.com" },
  "db": { "host": "admin-db.com", "port": "5432" },
  "features": { "darkmode": "true" }
}

Client app gets:

{
  "api": { "url": "https://client-api.com" },
  "auth": { "token": "client-token-123", "timeout": "30000" }
}

🔧 Enterprise Azure Integration

Per-App Azure App Configuration

import { createConfigServer } from 'react-azure-config/server';

// Server setup with automatic app discovery
const server = createConfigServer({
  port: 3001,
  environment: 'production'
});

await server.start();

Azure Authentication per App:

# Admin app Azure credentials
AZURE_APP_CONFIG_ENDPOINT_ADMIN=https://admin-config.azconfig.io
AZURE_CLIENT_ID_ADMIN=admin-client-id
AZURE_CLIENT_SECRET_ADMIN=admin-secret
AZURE_TENANT_ID_ADMIN=admin-tenant-id

# Client app Azure credentials  
AZURE_APP_CONFIG_ENDPOINT_CLIENT=https://client-config.azconfig.io
AZURE_CLIENT_ID_CLIENT=client-client-id
AZURE_CLIENT_SECRET_CLIENT=client-secret

# Shared tenant (optional)
AZURE_TENANT_ID=shared-tenant-id

Azure App Configuration Setup (per app):

# Admin app configuration in Azure
ApplicationInsights:ConnectionString = @Microsoft.KeyVault(SecretUri=https://admin-vault.vault.azure.net/secrets/insights-admin/)
Database:ConnectionString = @Microsoft.KeyVault(SecretUri=https://admin-vault.vault.azure.net/secrets/db-admin/)
Features:DarkMode = true
Api:BaseUrl = https://admin-api.production.com

# Client app configuration in Azure  
ApplicationInsights:ConnectionString = @Microsoft.KeyVault(SecretUri=https://client-vault.vault.azure.net/secrets/insights-client/)
Auth:TokenEndpoint = https://auth.production.com
Features:Analytics = true

🔍 Enterprise Debugging & Monitoring

Configuration Source Debugging

# Debug configuration precedence for admin app
GET /config-sources/admin

# Response shows full precedence chain:
{
  "appId": "admin",
  "precedenceChain": [
    {
      "priority": 5,
      "source": "azure",
      "configured": true,
      "endpoint": "https://admin-config.azconfig.io",
      "hasClient": true
    },
    {
      "priority": 4, 
      "source": "app-env-vars",
      "configured": true,
      "variables": ["REACT_APP_ADMIN_API_URL", "REACT_APP_ADMIN_DB_HOST"]
    },
    {
      "priority": 3,
      "source": "generic-env-vars", 
      "configured": true,
      "variables": ["REACT_APP_LOG_LEVEL"]
    }
  ]
}

App Discovery Information

# See how apps were discovered
GET /apps/discovered

# Response:
{
  "discoveryMethods": {
    "filesystem": {
      "apps": ["admin", "client"], 
      "count": 2
    },
    "environment": {
      "apps": ["admin", "client", "analytics"],
      "count": 3,
      "pattern": "REACT_APP_{APP_ID}_{VAR}"
    }
  },
  "combined": {
    "apps": ["admin", "client", "analytics"],
    "count": 3
  }
}

Performance Monitoring

# Get cache performance stats
GET /info

# Response includes enhanced cache metrics:
{
  "cacheStats": {
    "hitRate": 94,
    "layers": [
      { "name": "azure", "utilization": 45, "ttl": 900000 },
      { "name": "env-vars", "utilization": 78, "ttl": 300000 }
    ]
  }
}

📚 Complete API Reference

Multi-App Configuration Endpoints

# App-specific configuration
GET /config/admin                 # Admin app full config
GET /config/admin/api.url         # Admin app specific value
GET /config/client                # Client app full config
GET /config/client/auth.token     # Client app specific value

# App management
GET /apps                         # List all discovered apps
GET /apps/discovered              # Show app discovery methods
POST /refresh/admin               # Refresh admin app cache
POST /refresh/client              # Refresh client app cache

# Debugging & diagnostics
GET /config-sources/admin         # Show admin app config sources
GET /config-debug/admin           # Debug admin app configuration
GET /config-sources/client        # Show client app config sources

# Server management (unchanged)
GET /config                       # Default config (backward compatible)
GET /health                       # Health check
GET /info                         # Server info with cache stats

React Hooks (Enhanced)

// Multi-app configuration hooks
const { data: adminConfig } = useConfig(); // When used in <ConfigProvider appId="admin">
const adminApiUrl = useConfigValue('api.url'); // Gets admin-specific value

// App-aware context
const { appId, config, loading, error } = useConfigContext();

// Feature flags with app context
const showAdminFeature = useFeature('advancedDashboard'); // App-specific feature

Server-Side Usage

import { AppScopedConfigurationProvider } from 'react-azure-config/server';

const provider = new AppScopedConfigurationProvider();

// Get configuration for specific apps
const adminConfig = await provider.getAppConfiguration('admin');
const clientConfig = await provider.getAppConfiguration('client');

// Get specific values
const adminApiUrl = await provider.getAppConfigValue('admin', 'api.url');
const clientAuthToken = await provider.getAppConfigValue('client', 'auth.token');

// Discover available apps
const availableApps = provider.getAvailableApps(); // ['admin', 'client', 'analytics']

// Get Azure configuration info for debugging
const adminAzureInfo = provider.getAzureConfigInfo('admin');

🚀 Advanced Multi-Level Caching

Intelligent cache layers with automatic invalidation:

Azure Config Cache (15min TTL) - Long-lived external service data
Environment Variables Cache (5min TTL) - With change detection
File-based Cache (2min TTL) - With file modification detection
Merged Configuration Cache (1min TTL) - Final assembled config

Features:

✅ Environment variable change detection
✅ File modification monitoring
✅ Automatic cache invalidation
✅ Cache warming and pre-loading
✅ Performance metrics and hit rates
✅ Memory usage optimization

🌟 Framework Compatibility

Full SSR (Server-Side Rendering) Support:

✅ Next.js - App Router & Pages Router
✅ Remix - Hydration-safe components
✅ Gatsby - SSG and SSR modes
✅ Create React App - Standard SPA mode
✅ Vite - All deployment targets

Zero hydration errors - Components render consistently between server and client.

🔐 Security & Enterprise Features

✅ Azure Key Vault integration with automatic secret resolution
✅ Service Principal authentication for production deployments
✅ Managed Identity support for Azure-hosted applications
✅ Directory traversal protection in app ID validation
✅ Environment variable sanitization and validation
✅ Secure credential handling with no secrets in client code

🏗️ How Multi-App System Works

App Discovery - Automatically detect apps from environment variables (REACT_APP_ADMIN_*) and filesystem (apps/admin/)
Configuration Loading - Each app gets isolated configuration using the precedence chain
Smart Caching - Multi-level caching with app-specific invalidation
Runtime Serving - Express server provides app-specific endpoints (/config/admin, /config/client)
Docker Integration - Same image serves multiple apps with different configurations

🎯 Use Cases

Enterprise Monorepo

Multiple React apps in single repository
Shared components with app-specific configurations
Per-app Azure App Configuration instances
Isolated Application Insights per app

Microservices Frontend

Multiple frontend apps for different domains
Shared configuration infrastructure
App-specific feature flags and settings
Centralized monitoring and debugging

Multi-Tenant Applications

App-per-tenant configurations
Tenant-specific Azure resources
Isolated configuration and monitoring
Dynamic app discovery and provisioning

📈 Performance Benchmarks

Cache Hit Rate: 95%+ in production workloads
Configuration Load Time: <50ms average
Memory Usage: <10MB for 100+ configuration keys
Environment Change Detection: <1s
Docker Startup: No additional overhead

⚛️ React 19 Compatibility

Full React 19 support with improved TypeScript integration:

✅ Modern React patterns - Uses function components instead of React.FC
✅ Improved type safety - Better TypeScript integration with React 19
✅ Optimized imports - Cleaner dynamic imports for optional peer dependencies
✅ Enhanced SSR safety - Better server-side rendering compatibility

AppInsights Provider Updates

The AppInsightsProvider has been modernized for React 19:

import { AppInsightsProvider } from 'react-azure-config/client/insights';

// Modern function component syntax
export function App() {
  return (
    <AppInsightsProvider config={{ connectionString: 'your-connection-string' }}>
      <YourApp />
    </AppInsightsProvider>
  );
}

What's New:

Removed React.FC usage for better type inference
Improved dynamic import handling for @microsoft/applicationinsights-* packages
Enhanced TypeScript compatibility with React 19's stricter type checking
Optional peer dependency metadata for cleaner npm installations

🔐 NextAuth Integration

Seamlessly integrate with NextAuth.js using Azure App Configuration:

Server-Side Environment Loading

NextAuth requires environment variables at server startup. Use our Azure environment loader:

// next.config.js or server startup
import { loadAzureToProcessEnv } from 'react-azure-config/server';

// Load Azure config to process.env before NextAuth initializes
await loadAzureToProcessEnv({
  appId: 'admin', // For multi-app scenarios
  nextAuth: {
    mappings: {
      'auth.nextauth.secret': 'NEXTAUTH_SECRET',
      'auth.nextauth.url': 'NEXTAUTH_URL',
      'auth.okta.clientId': 'OKTA_CLIENT_ID',
      'auth.okta.clientSecret': 'OKTA_CLIENT_SECRET',
      'auth.okta.issuer': 'OKTA_ISSUER'
    }
  }
});

Environment Variable Mapping

Configure your Azure App Configuration with these keys:

// Azure App Configuration keys
{
  "auth.nextauth.secret": "your-nextauth-secret",
  "auth.nextauth.url": "https://yourapp.com",
  "auth.okta.clientId": "0oa239lmlarKA38vh0h8",
  "auth.okta.clientSecret": "your-okta-secret",
  "auth.okta.issuer": "https://yourorg.okta.com/"
}

Multi-App NextAuth Setup

For monorepos with multiple apps:

// Admin app
import { createAppAzureLoader } from 'react-azure-config/server';

const adminLoader = createAppAzureLoader('admin');
await adminLoader.loadToProcessEnv();

// Client app  
const clientLoader = createAppAzureLoader('client');
await clientLoader.loadToProcessEnv();

Advanced Usage

import { AzureEnvironmentLoader } from 'react-azure-config/server';

export const azureLoader = new AzureEnvironmentLoader({
  appId: 'admin',
  endpoint: process.env.AZURE_APP_CONFIG_ENDPOINT_ADMIN,
  authentication: {
    type: 'servicePrincipal',
    clientId: process.env.AZURE_CLIENT_ID_ADMIN,
    clientSecret: process.env.AZURE_CLIENT_SECRET_ADMIN,
    tenantId: process.env.AZURE_CLIENT_TENANT_ID_ADMIN
  },
  customMappings: {
    'database.connectionString': 'DATABASE_URL',
    'api.baseUrl': 'SGJ_INVESTMENT_BASE_URL'
  },
  cacheTtl: 5 * 60 * 1000 // 5 minutes
});

// Load before app initialization
await azureLoader.loadToProcessEnv();

Benefits:

🚀 Zero NextAuth changes - Works with existing NextAuth configuration
🔄 Automatic refresh - Built-in caching with configurable TTL
🛡️ Secure fallback - Graceful degradation to local environment variables
📦 Multi-app support - Perfect for monorepo environments

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

🔗 Links

Built with ❤️ by Jovani Samuels

The ultimate solution for enterprise React configuration management with Azure integration and monorepo support.