React Integration

Official React SDK for App Config.json. Type-safe hooks, real-time sync, and zero-config setup.

Installation

Install the React SDK using your preferred package manager. Requires React 18+.

Terminal

# npm
npm install @appconfigjson/react

# yarn
yarn add @appconfigjson/react

# pnpm
pnpm add @appconfigjson/react

Provider Setup

Wrap your application with <AppConfigProvider> to initialize the client and enable real-time configuration synchronization.

src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { AppConfigProvider } from '@appconfigjson/react'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <AppConfigProvider
      appKey="your_app_key_here"
      environment="production"
      refreshInterval={5000} // optional: polling fallback
    />
    <App />
  </StrictMode>
)

⚡ Note: The SDK automatically uses WebSocket/SSE for instant updates. refreshInterval only serves as a fallback if real-time transport is unavailable.

Basic Usage

Access configurations using the built-in React hooks. All values are reactive and automatically update when the remote config changes.

src/components/FeatureToggle.tsx

import { useConfig } from '@appconfigjson/react'

export default function FeatureToggle() {
  const { data, isLoading, error } = useConfig()

  if (isLoading) return <div>Loading config...</div>
  if (error) return <div>Config error: {error.message}</div>

  return (
    <div>
      <p>App Version: {data.version}</p>
      <p>Dark Mode: {data.features.darkMode ? 'Enabled' : 'Disabled'}</p>
      <p>API Endpoint: {data.endpoints.api}</p>
    </div>
  )
}

Hooks API

useConfig()

Returns the full configuration object along with loading and error states.

Property	Type	Description
`data`	`ConfigType`	The current configuration object
`isLoading`	`boolean`	True while fetching initial config
`error`	`ConfigError \| null`	Error object if fetch/update fails

useConfigValue(path)

Selects a specific nested value. Re-renders only when that specific path changes.

Usage Example

import { useConfigValue } from '@appconfigjson/react'

function ThemeSwitcher() {
  const isDark = useConfigValue('features.darkMode')
  const maxUsers = useConfigValue('limits.maxUsers')

  return <div>Dark: {isDark}, Max: {maxUsers}</div>
}

Config Subscriptions

Listen to raw configuration changes without triggering React renders.

useEffect Pattern

import { useConfigSubscription } from '@appconfigjson/react'

useConfigSubscription((newConfig, previousConfig) => {
  console.log(`Config updated from v${previousConfig.version} to v${newConfig.version}`)
  // Perform side effects: analytics, logger, custom logic
}, ['features.betaEnabled']) // Optional: subscribe to specific paths

TypeScript Support

The SDK is fully typed. Define your configuration schema to get autocomplete and type safety across your app.

config.ts

import { defineConfig } from '@appconfigjson/react'

export const AppConfig = defineConfig({
  app_name: "my-app",
  version: "3.0.0",
  environment: "production",
  features: {
    realtime_sync: true,
    max_retries: 3,
    timeout_ms: 5000
  },
  endpoints: {
    api: "https://api.appconfig.json/v3"
  }
})

// Usage: type-safe everywhere
type ConfigType = typeof AppConfig

Next.js / SSR Compatibility

The SDK works seamlessly with Next.js App Router and Pages Router. For SSR environments, wrap usage in a client-only component or use dynamic imports to avoid hydration mismatches.

Next.js Client Component

"use client"

import { useConfig } from '@appconfigjson/react'

export default function DashboardConfig() {
  const { data, isLoading } = useConfig()
  return isLoading ? <div>Loading...</div> : <div>Ready</div>
}

Testing

Use the provided test utilities to mock configurations in Jest/Vitest.

__tests__/config.test.tsx

import { render, screen } from '@testing-library/react'
import { mockAppConfig } from '@appconfigjson/react/testing'
import FeatureToggle from '../FeatureToggle'

mockAppConfig({
  features: { darkMode: true }
})

test("renders with dark mode enabled", () => {
  render(<FeatureToggle />)
  expect(screen.getByText('Enabled')).toBeInTheDocument()
})

← Node.js Integration API Reference →