[Compiler Bug]: React Compiler breaks most functionality of TanStack Table

[skoshx]

What kind of issue is this?

• React Compiler core (the JS output is incorrect, or your app works incorrectly after optimization)
• babel-plugin-react-compiler (build issue installing or using the Babel plugin)
• eslint-plugin-react-compiler (build issue installing or using the eslint plugin)
• react-compiler-healthcheck (build issue installing or using the healthcheck script)

Link to repro

https://github.com/skoshx/react-compiler-bug-repro

(edit: Open in StackBlitz as https://stackblitz.com/github/skoshx/react-compiler-bug-repro)

Repro steps

1. bun install
2. bun dev
3. Try to interact with the data table, nothing works: filter input doesn't work. columns dropdown doesn't work (clicking doesn't do anything), clicking on the checkboxes doesn't update react UI state.
4. disable reactCompiler, and all problems disappear

How often does this bug happen?

Every time

What version of React are you using?

"react": "^19.1.0"

What version of React Compiler are you using?

"babel-plugin-react-compiler": "^19.1.0-rc.1",

[josephsavona]

Thanks for posting a repro for this, it gives us something concrete to look at.

First off, we recognize that it's frustrating that React Compiler doesn't work out of the box with a library that you'd been using. Our goal with the beta period and RC period is to help figure out incompatibilities like this — so again, thanks for letting us know about this issue so that we can try to figure out a path forward. For you and others trying to use the compiler with TanStack Table, note that you can disable React Compiler for specific components or hooks where you're using incompatible libraries.

For those interested in understanding why this issue happens, and potential next steps, read on.

Deep Dive

Here's a distilled version of the code, which strips away everything but the input for the filter text:

export function DataTableDemo() {
  const [sorting, setSorting] = React.useState < SortingState > ([])

  const table = useReactTable({
    data,
    state: {
      sorting,
    },
  })

  // It should be safe to wrap this in useMemo and only
  // recalculate when `table` changes:
  //
  // ```
  // const inputValue = useMemo(() => {
  //   return table.getColumn("email")?.getFilterValue() ?? "";
  // }, [table]);
  // ```
  //
  // But useReactTable modifies the existing table state
  // rather than create a new state.
  const inputValue = table.getColumn("email")?.getFilterValue() ?? "";

  const inputOnChange = (event) =>
    table.getColumn("email")?.setFilterValue(event.target.value);
  return (
    <Input
      placeholder="Filter emails..."
      value={inputValue}
      onChange={inputOnChange}
      className="max-w-sm"
    />
  )
}

Load this in the compiler playground

As the comment explains, React is built around the idea of immutable updates. If part of state changes, the way to indicate that to React is by creating a new object with fields updated as necessary. Our Rules of React docs give more examples of this.

TanStack Table appears to modify state values in-place (in the example, the table object), meaning that React can't tell that anything has changed. Note that the stale values you're seeing with this example would also occur if the user manually memoized inputValue with useMemo, setting table as the dependency, as it should be safe to do.

Next Steps on TanStack Table

In terms of addressing the issue: React and React Compiler is built around the idea of immutable updates. Immutable updates aren't just a mechanism for determining what's changed, they also unlock the ability to render multiple versions of the UI for things like transitions and now view transitions. TanStack Table was built before some of these features were available, before we had clearly documented the Rules of React, and before React Compiler was available, so it's understandable that the team chose the architecture that they did.

We've had some conversations with Tanner about this, and the main thing that would help us is to understand what if any specific performance problems would occur if the library was built around immutable updates instead of mutating in-place. We're constantly on the lookout for patterns that aren't well-optimized by the existing compiler and adding improvements (some short-term, some longer-term). We'd love to help TanStack folks update the library to use immutable updates and if there are concrete examples that are slow we can collaborate on ways to address the performance gaps.

[skoshx]

Hey, thanks for this explanation! I'm not sure if this is possible currently with React Compiler or their lint rules or something, but would it be possible to check if any of the dependencies that I'm using are breaking the Rules of React? Because my worry currently after this experience was that, I might upgrade to React Compiler, and everything will seem okay on the surface, but I will have to manually test everything to double check things don't break.

What would be great is getting a really loud warning / error message saying something like "Hey, you're using [Library X], which actually breaks the Rules of React, so it might not be compiled right"

Not sure if React Compiler has this functionality though, but would be nice to build confidence and transparency of potential problems :)

[josephsavona]

@skoshx We actually had a version of that in a "healthcheck" script that we recommended, but we had mixed results. I feel you though, it would be great to help people avoid this. We do recommend testing your app with the compiler for this and other reasons, see https://react.dev/blog/2025/04/21/react-compiler-rc#upgrading-react-compiler for a bit more context.

cc @poteto for the feedback, maybe we could do something with a postinstall script for babel-plugin-react-compiler instead, so that it's just part of normal installation?

[NikxDa]

Here's the relevant issue in TanStack Table's repository:
TanStack/table#5567

Also a quick note here that the RC healthcheck does not currently highlight this library as incompatible.

[zeorin]

The issue is that the compiler will transform something like

const state = table.getState()

to the equivalent of:

const state = useMemo(() => table.getState(), [table])

TanStack table returns a stable reference for table, so that means that we cannot get the freshest updates during renders, unless we opt out of memoization.

There is a way to do so in a fine-grained manner, since one can "use no memo" in a hook scope only.

Consider the following hook:

const useNoMemo = <const T>(factory: () => T): T => {
  'use no memo';
  return factory();
};

This allows us to write

const state = useNoMemo(() => table.getState())

and this will work as it would have before the compiler, without opting your entire component out of the compiler.

[zeorin]

We've had some conversations with Tanner about this, and the main thing that would help us is to understand what if any specific performance problems would occur if the library was built around immutable updates instead of mutating in-place.

In order to improve the performance of TanStack Table I actually copy the table state into a Zustand Store which I place in a context and then use selectors for fine-grained updates in the table components.

I can confidently say that taking a modern approach to immutable updates would vastly improve the performance of TanStack table.

[josephsavona]

In order to improve the performance of TanStack Table I actually copy the table state into a Zustand Store which I place in a context and then use selectors for fine-grained updates in the table components.

@zeorin Super interesting! Is there any chance you could share a smaller repro of the pattern you use? We'd love to have a small app that we can use as a benchmark to collaborate with TanStack folks and other libraries.

[zeorin]

@josephsavona https://codesandbox.io/p/github/zeorin/tanstack-table-perf/main

The core trick is really:

1. wrap the core table instance in something that useSyncExternalStore can integrate with (observer.ts), and
2. provide that to interested components via the context, which query it using useSyncExternalStoreWithSelector, in my case I created a useTable hook that does that (use-table.ts
3. Wrap the components in React.memo so they only re-render when uSES triggers them to (I'm using the compiler in my demo, instead).

My observer calls uSES's onStoreChange on state updates. Any component interested in the state can get it via a selector. Much of the TanStack table API was designed to be called during render, so instead I call those functions in the selector and return their values. I've set it up so that it checks for shallow equality by default (since the common case is to return an object of various values from the selector).

The exception to that is event handlers, those I get in the function body itself, because TanStack Table returns a new instance of those handlers on each call to e.g. getToggleSelectedHandler, even though it doesn't semantically change at all.

My demo renders 10000 rows using MUI's Table components. Initial render is chunky, but when selecting a row it's pretty quick, because only that row is re-rendered.

Using virtualization can of course speed things up a lot more, especially for state changes that affect all rows. In those cases a tip is to override the default CSS display for the table elements and use CSS grid and subgrid instead. This is so that one can position the rows with a transform, which is more performant than using a dummy spacer row instead. I didn't add virtualization to the demo because it's not really pertinent to the core perf issues TanStack Table has.

[zeorin]

@KevinVandy @TanStack perhaps my approach could be mentioned in TanStack/table#5567 to help people out so long (it's currently locked to collaborators only)?

I also have some ideas about improving the performance of the table core, such as by using Maps/Sets and data structures that are optimized for query speed (e.g. specialised read models for specific queries).