Feature: Support React Compiler without requiring useMemo for machine factories

[PaulRBerg]

Context

With React 19 and React Compiler, manual memoization via useMemo and useCallback is no longer recommended - the compiler automatically optimizes re-renders. However, @xstate/react's useActor hook compares logic.config by reference, which means machines created via factory functions (like setup().createMachine()) must still be wrapped in useMemo to prevent infinite re-render loops.

The Problem

When using a factory function to create a machine with dynamic config (e.g., passing wagmi config):

// This causes an infinite loop without useMemo
function MyComponent() {
  const config = useConfig();
  const machine = createMyMachine(config); // New reference each render
  const [state] = useActor(machine); // useActor detects "new" machine → setCurrent → re-render → loop
}

The workaround requires explicit memoization:

function MyComponent() {
  const config = useConfig();
  // Must memoize to prevent infinite loop
  const machine = useMemo(() => createMyMachine(config), [config]);
  const [state] = useActor(machine);
}

This works, but conflicts with React Compiler's philosophy of automatic memoization.

Proposed Solution

Consider one of these approaches:

1. Deep equality check on machine config - Instead of reference equality on logic.config, use a deep comparison or hash of the relevant config properties.

2. Stable machine identity hook - Provide a useStableMachine or similar that handles the memoization internally based on a user-provided dependency array.

3. Document React Compiler compatibility - If this is intentional behavior, clearly document that useMemo is still required for factory-created machines even with React Compiler.

Environment

• XState v5
• @xstate/react
• React 19 with React Compiler

Related Issues

• Allow useMachine to accept a new machine between renders #1101 - "Allow useMachine to accept a new machine between renders" (closed 2020)
• Why useConstant? #913 - "Why useConstant?" (closed 2019)

[davidkpiano]

Can you post some example code of what the config looks like?

For reference, if the machine definition stays the same (which ideally it should) and the only thing you're configuring is provided actions, actors, guards, etc., then this will already work:

const [state, send] = useMachine(
  someMachine.provide({
    // actors, guards, etc. - it will be stable!
  })
);

[PaulRBerg]

Here's a concrete example (which uses Effect-ts:

Example: Factory-created machine with injected runtime

// Factory function that creates machine with injected runtime
function createAllowanceMachine(runtime: EffectRuntime) {
  return setup({
    types: { context: {} as AllowanceContext, events: {} as AllowanceEvent },
    actors: {
      checkAllowance: fromPromise(({ input }) => 
        Effect.runPromise(checkAllowanceEffect(input).pipe(Effect.provide(runtime)))
      ),
    },
  }).createMachine({ id: 'allowance', initial: 'idle', /* states */ });
}

// In the hook
function useAllowance(params: AllowanceParams) {
  const runtime = useEffectWeb3Runtime();
  
  // ❌ Infinite re-renders
  const machine = createAllowanceMachine(runtime);
  const [snapshot, send] = useActor(machine);
  
  useEffect(() => {
    send({ type: "CHECK", params });
  }, [params, send]); // send changes every render → effect fires → re-render → loop
}

Why .provide() doesn't help: We need the runtime at machine creation time because actors use it in fromPromise callbacks. We're not providing implementations to an existing machine—we're building the machine with injected dependencies.

Workaround:

const machine = useMemo(() => createAllowanceMachine(runtime), [runtime]);

Suggestion: Could useActor accept a factory + deps? e.g. useActor(() => createMachine(runtime), [runtime])