react-volatile

Chaos engineering for React applications.

Inject controlled failures into hooks, components, and async operations during development and testing. Find out how your app behaves when things go wrong — before your users do.

Install

npm install @react-volatile/react

Or with pnpm:

pnpm add @react-volatile/react

Quick Start

Wrap your app with VolatileProvider and swap React hooks for their volatile equivalents:

import { VolatileProvider, useVolatileState, ChaosPanel } from '@react-volatile/react';

function App() {
  return (
    <VolatileProvider config={{ chaos: { defaultProbability: 0.3 } }}>
      <Counter />
      <ChaosPanel />
    </VolatileProvider>
  );
}

function Counter() {
  const [count, setCount] = useVolatileState(0, {
    name: 'count',
    component: 'Counter',
    failures: ['delay', 'error', 'corrupt'],
  });

  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

When chaos triggers, state updates may be delayed, throw errors, or corrupt values. The ChaosPanel shows a live feed of chaos events — toggle it with Ctrl+Shift+V.

How It Works

Each volatile hook wraps a standard React hook. On every call, the ChaosEngine rolls against a probability to decide whether to inject a failure. If it fires, it picks a random failure mode from the allowed set and applies it.

• Seeded RNG — pass a seed in config for reproducible chaos sequences across runs.
• Targeting — include or exclude specific components, hooks, or file patterns.
• Production-safe — the provider auto-disables when NODE_ENV=production.

Packages