Configuration

Control what breaks, when, and how often.

VolatileProvider

All configuration is passed through the provider:

<VolatileProvider
  config={{ chaos: { defaultProbability: 0.3, seed: 42 } }}
  disabled={false}
>
  {children}
</VolatileProvider>

Prop	Type	Description
`config`	`DeepPartial<ChaosConfig>`	Engine configuration (all fields optional)
`disabled`	`boolean`	Force disable. Defaults to `true` in production.

ChaosConfig Shape

{
  enabled: boolean,          // master switch (default: true)

  chaos: {
    defaultProbability: number,  // 0–1 (default: 0.3)
    delayRange: [number, number], // ms (default: [100, 3000])
    seed: number,                // for reproducible sequences
  },

  microscopic: {
    state:   { enabled, probability?, failures? },
    effect:  { enabled, probability?, failures? },
    context: { enabled, probability?, failures? },
    async:   { enabled, probability?, failures? },
  },

  macroscopic: {
    render:  { enabled, probability?, failures? },
    mount:   { enabled, probability?, failures? },
    unmount: { enabled, probability?, failures? },
    lazy:    { enabled, probability?, failures? },
  },

  targeting: {
    include: TargetPattern[],
    exclude: TargetPattern[],
  },

  scheduling: {
    pattern: 'continuous' | 'burst' | 'scheduled',
    burstInterval?: number,      // ms between burst toggles
    schedule?: { start, end }[], // time windows in ms
  },

  logging: {
    enabled: boolean,
    level: 'error' | 'warn' | 'info' | 'debug',
    transport?: { send(event: ChaosEvent): void },
  },

  devtools: {
    enabled: boolean,
    showIndicator: boolean,
    hotkey: string,
  },
}

Targeting

Control which components and hooks are affected. Include patterns act as an allowlist. Exclude patterns always take priority.

<VolatileProvider config={{
  targeting: {
    include: [
      { type: 'component', pattern: 'Dashboard' },
      { type: 'hook', pattern: /^fetch/ },
    ],
    exclude: [
      { type: 'component', pattern: 'AuthForm' },
    ],
  },
}}>
  {children}
</VolatileProvider>

Pattern Type	Matches Against
`component`	Component name string
`hook`	Hook name / target string
`file`	File path (useful with babel plugin)

Patterns can be a plain string (uses includes matching) or a RegExp.

Scheduling

Continuous

Default. Chaos can trigger on every hook call.

Burst

Alternates between active and inactive periods. Controlled by burstInterval (default 5000ms).

scheduling: { pattern: 'burst', burstInterval: 3000 }

Scheduled

Only active during specific time windows (ms elapsed since engine start).

scheduling: {
  pattern: 'scheduled',
  schedule: [
    { start: 0, end: 5000 },      // first 5 seconds
    { start: 10000, end: 15000 },  // 10s–15s mark
  ],
}

Seeded Randomness

Pass a seed to make chaos sequences deterministic. The same seed produces the same sequence of triggers and failure selections.

chaos: { seed: 42 }

The current seed is displayed in the ChaosPanel header for easy reproduction.

Devtools

ChaosPanel

Floating panel that shows a live event feed. Toggle with Ctrl+Shift+V (configurable via devtools.hotkey). Supports filtering by chaos type and clearing history.

import { ChaosPanel } from '@react-volatile/react';
// place inside VolatileProvider
<ChaosPanel />

ChaosIndicator

Small badge that shows event count and pulses on chaos. Accepts a position prop: top-left, top-right, bottom-left, bottom-right.

import { ChaosIndicator } from '@react-volatile/react';
<ChaosIndicator position="bottom-left" />