What is the recommended way to provide an XState machine instance that depends on external props?

[inakiarroyo]

Hi everyone 👋

I'm working on integrating an XState machine (tagMachine) into a React project and want to clarify the best approach for initialising and providing an interpreter instance based on external props (e.g., tags, isNote, onTagsUpdate). My goal is to keep the interpreter:

• Stable across renders
• Recreated only when necessary (e.g., when entryType or selectedTags should be reset)
• Performance-friendly, avoiding unnecessary restarts or leaks

Ensure a stable machine instance

We want the machine to remain stable between renders, unless a meaningful prop change requires resetting the machine (e.g., switching from "note" to "message" mode)

🅰️ Alternative A: interpret + useMemo

Here I use useMemo to memoize and interpret(...).start() directly:

const tagMachineRef = useMemo(
  () =>
    interpret(
      tagMachine
        .withContext({
          entryType: isNote ? 'note' : 'message',
          selectedTags: tags ?? [],
          tags: [],
        })
        .withConfig({
          actions: {
            onUpdate: ({ selectedTags }) =>
              onTagsUpdate?.(selectedTags),
          },
        })
    ).start(),
  [tags, isNote, onTagsUpdate]
);

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

<TagsMachineProvider
  tags={tags}
  isNote={isNote}
  onTagsUpdate={onTagsUpdate}
/>

Possible Pros:

• Machine instance resets when inputs change
• Easy to control when it’s recreated via deeps array

Possible Cons:

• The interpreter is created during render, which might go against React best practices?
• It might not clean up old interpreters - potentially leading to memory leaks?

🅱️ Alternative B: useInterpret + key remount

Here, I use useInterpret from @xstate/react, and rely on key at the component level to force remounting the provider:

const tagMachineRef = useInterpret(tagMachine, {
  context: {
    entryType: isNote ? 'note' : 'message',
    selectedTags: tags ?? [],
    tags: [],
  },
  actions: {
    onUpdate: ({ selectedTags }) =>
      onTagsUpdate?.(selectedTags),
  },
});

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

const updaterKey = useMemo(
  () =>
    `${isNote ? 'note' : 'message'}-${[...(tags ?? [])].sort().join(',')}`,
  [isNote, tags]
);

<TagsMachineProvider
  tags={tags}
  isNote={isNote}
  onTagsUpdate={onTagsUpdate}
  key={updaterKey}
/>

Possible Pros:

• useInterpret starts the service in a React-safe way (in an useEffect)?
• React handles cleanup when the key changes - no manual stop needed?

Possible Cons:

• Slightly more boilerplate at the usage site
• Less granular control over when the machine is recreated (depends on key implementation)

Why I moved away from useInterpret initially

I initially used useInterpret directly, but found that it does not recreate the interpreter when the machine config/context changes. The interpreter remained the same across renders. This meant selectedTags, entryType, etc., were only set on initial mount, unless I manually sent sync events.

This led me to consider using interpret directly inside useMemo - until I realised that doing so might introduce render-phase side effects and potential memory leaks.

❓ My Questions

1. Which approach is considered more correct / idiomatic with XState v4/v5?
2. Is Alternative B with useInterpret + key the recommended way to safely recreate interpreters with new context/config?
3. Are there better alternatives I should consider?
4. Are my assumptions above about possible pros/cons of each approach correct? Especially regarding render-phase side effects and interpreter cleanup behaviour?

Any thoughts, insights, or best practices would be super appreciated 🙏

Thanks in advance!

[davidkpiano]

Before providing a detailed answer, would it be possible to migrate to XState v5? interpreter/useInterpret is part of v4, and significant improvements have been made since then in the latest version.

[inakiarroyo]

Hello @davidkpiano,

Thank you for reaching out. At the moment, our project has a strong dependency on v4, and upgrading to v5 is quite challenging. However, it would still be possible in the future. Would it be possible for you to provide two separate solutions: one compatible with v4 and another for v5? This would allow us to integrate the v4 version right away in our current setup, while also having a clear reference for how to implement it once we upgrade to v5.