Babel Plugin

Automatic hook transformation at build time.

Instead of manually replacing every useState with useVolatileState, let the babel plugin do it for you.

Install

npm install -D @react-volatile/babel-plugin

Configure

Add to your Babel config:

{
  "plugins": ["@react-volatile/babel-plugin"]
}

Or with options:

{
  "plugins": [
    ["@react-volatile/babel-plugin", {
      "mode": "all",
      "include": ["src/components/"],
      "exclude": ["src/components/Auth"]
    }]
  ]
}

Options

Option	Type	Default	Description
`mode`	`"all" \| "marked"`	`"all"`	Transform all hooks or only those with a `@volatile` comment
`include`	`string[]`	`[]`	Only transform files matching these patterns
`exclude`	`string[]`	`[]`	Skip files matching these patterns
`importSource`	`string`	`"@react-volatile/react"`	Custom import path for volatile hooks

What Gets Transformed

React Hook	Volatile Hook
`useState`	`useVolatileState`
`useEffect`	`useVolatileEffect`
`useLayoutEffect`	`useVolatileLayoutEffect`
`useReducer`	`useVolatileReducer`
`useMemo`	`useVolatileMemo`
`useCallback`	`useVolatileCallback`

Metadata Injection

The plugin automatically injects a metadata object into each transformed hook call with the component name, hook name, and source location:

// Input
import { useState } from 'react';
function Counter() {
  const [count, setCount] = useState(0);
}

// Output
import { useVolatileState } from '@react-volatile/react';
import { useState } from 'react';
function Counter() {
  const [count, setCount] = useVolatileState(0, {
    component: 'Counter',
    name: 'useState',
    location: { line: 3, column: 30 },
  });
}

Marked Mode

In "marked" mode, only hooks preceded by a // @volatile comment are transformed:

function App() {
  // @volatile
  const [count, setCount] = useState(0);  // transformed

  const [name, setName] = useState('');   // left alone
}

This is useful for gradually introducing chaos into specific hooks without affecting the entire codebase.