[docs] Performance considerations + playground

[zardoy]

Treat this issue as feedback and a suggestion to improve the docs and maybe create some possible stress tests for onboarding users (continue reading to see what the outcome of my experience was).

Hi! React Pixi is an amazing project, compared to vanilla plain usage it brings an insane development speed, powered by rich react lib & tooling ecosystem, and most importantly HMR updates that aren't possible with pixi in any other way... but it seems you lose something when you switch from vanilla - performance. And yet so far I haven't seen anything related in the docs related to this or anything that could help you to understand the performance implications of using React with Pixi. Yes, the degradation is not crazily big like it could be a few years ago and yet still can be not noticeable in some relatively small game projects (especially if your game is not dynamic or you use refs a lot) or on powerful machines.

Yes you can use refs to skip React updates overhead. However:

1. using refs feels like a hack to escape React reactivity and it brings you back to vanilla pixi experience, sometimes it can be confusing, annoying as you have to completely rewrite the code and sometimes not clear whether you should do it (if you can't really predict the number of updates it's going to receive per second).
2. Using refs to do some updates will create timing desync with React updates system (unpredictable batching, maybe different lanes?) so half of the app will be out of sync with the other half.

And when you try to optimize performance with React you should be aware of:

1. You get absolutely different performance results in dev/prod since React uses completely different builds/feature set relying on process.env.NODE_ENV variable. I haven't found a way to use the prod build in dev mode.
2. Pixi is single-threaded, so the worst part of that is that React due to its nature, is almost impossible to debug; you can get infinitely long recursivelyTraverseMutationEffects in the profiler, while without React you would always get meaningful stack traces even from the pixi itself.

While on very small demos it React feels the same on real world projects you might regret switching to React without having a way back. Yes, there are some tools like builtin Profiler, react-scan that can help you understand your component updates but even these tools are inconsistent and the process is incredibly tedious.

As I was digging down into sources to better understand this it seems I got that React is simply not created for tasks like this. Such performance issues might be visible only with Pixi since its really performant compared to react-dom. While React maybe is good for making responsive UI updates, it might not be for high-precision real-time updates.

If possible, this project should better provide some tools to help users to understand the performance implications of using React with Pixi by creating guides on what to do and what to avoid with different examples and stress tests.

Meanwhile, I created a very primitive test playground to show this in action:
https://github.com/zardoy/pixi-react-perf

(dev build, not prod)

Screen.Recording.2026-02-11.at.18.mp4