import { createContext, useContext, useMemo, useState, ReactNode } from 'react';

interface WorkspaceConfig {
  theme: 'system' | 'light' | 'dark';
  locale: string;
  activeProjectId: string | null;
}

interface WorkspaceContextValue extends WorkspaceConfig {
  updateTheme: (theme: WorkspaceConfig['theme']) => void;
  switchProject: (projectId: string) => void;
}

const WorkspaceContext = createContext<WorkspaceContextValue | undefined>(undefined);

interface WorkspaceProviderProps {
  children: ReactNode;
  initialConfig?: Partial<WorkspaceConfig>;
}

export function WorkspaceProvider({ children, initialConfig }: WorkspaceProviderProps) {
  const [theme, setTheme] = useState<WorkspaceConfig['theme']>(initialConfig?.theme ?? 'system');
  const [locale, setLocale] = useState(initialConfig?.locale ?? 'en-US');
  const [activeProjectId, setActiveProjectId] = useState<string | null>(initialConfig?.activeProjectId ?? null);

  const contextValue = useMemo<WorkspaceContextValue>(() => ({
    theme,
    locale,
    activeProjectId,
    updateTheme: setTheme,
    switchProject: setActiveProjectId,
  }), [theme, locale, activeProjectId]);

  return (
    <WorkspaceContext.Provider value={contextValue}>
      {children}
    </WorkspaceContext.Provider>
  );
}

export function useWorkspace(): WorkspaceContextValue {
  const context = useContext(WorkspaceContext);
  
  if (context === undefined) {
    throw new Error('useWorkspace must be used within a WorkspaceProvider');
  }
  
  return context;
}

wrapper.

import { WorkspaceProvider } from './providers/WorkspaceProvider';
import { DashboardShell } from './components/DashboardShell';
import { UserBadge } from './components/UserBadge';
import { SettingsPanel } from './components/SettingsPanel';

export function AppLayout() {
  return (
    <WorkspaceProvider initialConfig={{ theme: 'dark', locale: 'en-US' }}>
      <DashboardShell>
        <UserBadge />
        <SettingsPanel />
      </DashboardShell>
    </WorkspaceProvider>
  );
}

Consuming components remain completely decoupled from the provider hierarchy:

export function UserBadge() {
  const { theme, locale } = useWorkspace();
  
  return (
    <div className={`badge badge--${theme}`}>
      <span>Locale: {locale}</span>
    </div>
  );
}

export function SettingsPanel() {
  const { updateTheme } = useWorkspace();
  
  return (
    <section>
      <button onClick={() => updateTheme('light')}>Light</button>
      <button onClick={() => updateTheme('dark')}>Dark</button>
    </section>
  );
}

Architecture Decision: Notice that DashboardShell never receives theme or locale props. It acts as a layout container, unaware of the data flowing through it. This eliminates interface bloat and allows the component tree to evolve independently of state requirements.

Pitfall Guide

Context is powerful but introduces specific performance and architectural risks when misapplied. The following pitfalls represent the most common production failures.

1. The Monolith Context

Explanation: Developers often create a single AppContext containing authentication, theme, notifications, and feature flags. Any update to one property triggers re-renders in all consumers, regardless of whether they use that specific property. Fix: Split context by domain. Create separate AuthContext, ThemeContext, and FeatureFlagContext. Consumers only re-render when their specific domain state changes.

2. Unstable Provider Values

Explanation: Passing inline objects or functions directly to the value prop creates a new reference on every render. This defeats context optimization and causes cascading re-renders. Fix: Always wrap the context value in useMemo. Extract state setters and callbacks using useState or useCallback to guarantee reference stability.

3. Context for Transient UI State

Explanation: Using context to manage modal visibility, dropdown open states, or form step navigation introduces unnecessary global coupling. These states are inherently local and change frequently. Fix: Keep transient UI state in the nearest common ancestor using useState. Lift state only when sibling components require coordination. Context should be reserved for data that genuinely spans multiple unrelated branches.

4. Ignoring Component Tree Boundaries

Explanation: Context only flows downward through the React tree. Attempting to consume context in a component rendered outside the provider subtree (e.g., via portals or lazy-loaded routes mounted at the root) results in undefined values. Fix: Verify provider placement matches the consumption scope. For portal-based modals, duplicate the provider inside the portal root or use a context bridge pattern to forward values.

5. Missing Default Values & Type Safety

Explanation: Creating context without a default value or proper TypeScript typing leads to runtime errors and poor developer experience. Consumers must constantly check for undefined. Fix: Provide explicit defaults during createContext() or enforce provider usage with runtime checks in custom hooks. Use TypeScript generics to maintain strict typing across the application.

6. High-Frequency Updates Without Selectors

Explanation: Context triggers full consumer re-renders when the value changes. If a context holds frequently updating data (e.g., mouse coordinates, scroll position, or real-time metrics), performance degrades rapidly. Fix: Implement a selector pattern or split frequently changing data into a separate context. For extreme cases, consider external state management with built-in selector optimization.

7. Over-Engineering Small Applications

Explanation: Introducing context in a prototype or small utility app adds boilerplate without measurable benefit. The cognitive overhead of context boundaries outweighs the simplicity of prop passing for shallow trees. Fix: Defer context adoption until prop chains exceed three levels or multiple unrelated components require the same data. Start with props, refactor to context when the cost of maintenance becomes visible.

Production Bundle

Action Checklist

• Define explicit TypeScript interfaces for context value and provider props
• Create context with undefined default to enforce provider usage
• Wrap provider value in useMemo to stabilize references
• Implement a custom consumption hook with runtime error checking
• Split context by domain (auth, theme, config, notifications)
• Place providers at architectural boundaries, not inside leaf components
• Audit re-render frequency using React DevTools Profiler after implementation
• Document context boundaries and usage guidelines in team wiki

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Data shared between parent and immediate child	Prop Passing	Minimal boilerplate, explicit data flow	Negligible
Data needed across 3+ component levels	React Context	Eliminates interface bloat, stable maintenance cost	Low
Multiple unrelated branches need same data	React Context (split by domain)	Decouples consumers from hierarchy	Low-Medium
High-frequency updates (scroll, mouse, real-time)	External Store + Selectors	Context lacks built-in subscription optimization	Medium
Complex state logic with reducers/middleware	External Store (Redux/Zustand)	Context lacks devtools, time-travel, and middleware	High
Transient UI state (modals, dropdowns)	Local State + Lift	Context adds unnecessary global coupling	Negligible

Configuration Template

Copy this production-ready setup for new context implementations. Includes TypeScript typing, memoization, error handling, and selector-ready structure.

import { createContext, useContext, useMemo, useState, ReactNode } from 'react';

// 1. Define contracts
interface NotificationConfig {
  messages: Array<{ id: string; text: string; type: 'info' | 'warning' | 'error' }>;
  isDismissed: boolean;
}

interface NotificationContextValue extends NotificationConfig {
  addMessage: (msg: Omit<NotificationConfig['messages'][number], 'id'>) => void;
  clearAll: () => void;
}

// 2. Create with undefined default
const NotificationContext = createContext<NotificationContextValue | undefined>(undefined);

// 3. Provider with memoization
interface NotificationProviderProps {
  children: ReactNode;
  initialMessages?: NotificationConfig['messages'];
}

export function NotificationProvider({ children, initialMessages = [] }: NotificationProviderProps) {
  const [messages, setMessages] = useState(initialMessages);
  const [isDismissed, setIsDismissed] = useState(false);

  const value = useMemo<NotificationContextValue>(() => ({
    messages,
    isDismissed,
    addMessage: (msg) => {
      const newMsg = { ...msg, id: crypto.randomUUID() };
      setMessages((prev) => [...prev, newMsg]);
    },
    clearAll: () => {
      setMessages([]);
      setIsDismissed(true);
    },
  }), [messages, isDismissed]);

  return (
    <NotificationContext.Provider value={value}>
      {children}
    </NotificationContext.Provider>
  );
}

// 4. Custom hook with safety check
export function useNotifications(): NotificationContextValue {
  const ctx = useContext(NotificationContext);
  if (!ctx) throw new Error('useNotifications must be wrapped in NotificationProvider');
  return ctx;
}

// 5. Optional: Selector hook for performance
export function useNotificationCount(): number {
  const { messages } = useNotifications();
  return messages.length;
}

Quick Start Guide

1. Identify the data boundary: Determine which state must be accessible across multiple unrelated components. If it only flows between 1-2 components, stick with props.
2. Create the context file: Run the configuration template above. Replace Notification with your domain name (e.g., Auth, Theme, Cart).
3. Wrap the application root: Import the provider and place it in your top-level layout or router component. Pass initial configuration via props.
4. Consume in leaf components: Replace prop drilling with useYourContext() calls. Remove intermediate prop declarations from parent components.
5. Verify performance: Open React DevTools, enable the Profiler, and trigger state updates. Confirm that only direct consumers re-render, not intermediate layout components.

Context is not a replacement for prop passing or external state management. It is a targeted architectural tool for decoupling data consumers from the component tree. Apply it at domain boundaries, stabilize provider values, and split contexts by concern. When implemented correctly, it eliminates interface bloat, reduces maintenance overhead, and keeps component hierarchies clean as applications scale.