A while back, my team tried moving our tooling from ESLint and Prettier to Biome within a monorepo. To be honest, I initially thought it would be an instant fix—just swap one binary and call it a day. It turns out that without a solid strategy, a migration like this can easily turn into a nightmare that breaks the team's entire workflow.
From that experience, I realized one thing: don't just go for a "big bang" approach. It makes much more sense to do it in stages.
The safest sequence, in my opinion, is to first align the Biome formatter configuration to match our old Prettier setup. The goal here is to ensure that when we run the format command for the first time, there isn't a massive wave of code changes. After that, we can try running Biome in "shadow mode" in CI—basically letting it report issues without actually failing the build. Once things settle down and the errors aren't causing much noise, only then should we start stripping out the old tools one by one.
But of course, there are downsides to this process, too. Not everything went smoothly.
One headache we ran into was the "double-format" issue in the editor. In VS Code, if you aren't careful, Prettier and Biome can end up fighting each other every time you hit save. The result? Your file formatting constantly flips back and forth. To fix this, we had to make sure our editor configurations were perfectly synced and clearly documented in the README so the rest of the team wouldn't get confused.
Then there were the import paths. We actually forgot to add some generated files to the Biome ignore list. This resulted in thousands of warnings flooding the terminal, even though the code itself wasn't the problem. It taught me to get the ignore rules sorted before getting busy debating actual coding rules.
Another thing that often gets overlooked is commit hooks. If you're using Biome
in CI but still using Prettier via lint-staged on your local machine, you're
asking for trouble. Everything looks fine (green) locally, but the moment you
push to CI, it fails (red).
So, when should you actually avoid a migration like this?
I don't think everything needs to be replaced just because a new tool is faster. If the team is busy fighting production incidents or if there's a release freeze, just wait. You don't want a tooling change to distract the team or make cherry-picking a pain because of massive, unnecessary code format changes.
Migration isn't just about swapping tools; it's about managing the transition. If you break everything down into separate Pull Requests—starting with the installation, then testing in CI, and finally removing the old tools—the whole process feels much more controlled.
A short note for later.