As a matter of fact we did go through a major refactor of whole App from being jQuery powered to WebComponents powered.
Painful Parts, Pitfalls etc are:
Sit back, try, discuss, experiment with Libraries and Frameworks. The go ahead with Refactor; you don't wanna look back and say we must have chosen yyzz instead of xxzz.
The AJAX requests needed change in Data Structure of Response and hence increased the time needed to complete the refactor on time.
While you are at refactor, there is still work needed to be done. Work like Fixes, small feature improvements, legal requirements etc and that will push it further.
Best way is to keep one person in team ready to pick up these emergency tasks.
As the expectations keep increasing by time; pressure to finish also keeps increasing.
Best way is to plan the gradual Refactor; all at once Refactor can go wrong in many ways. Refactor -> Release; Refactor -> Release; and keep doing this until you have whole app refactored.
Don't try to make Design changes; this way you keep at-least one stakeholder out of the loop; Design Team
Think from beginning about the tools needed to be used; configurations etc. Discuss and Agree on App Structure and patterns so that everyone in team knows about those
While we were refactoring, we were coding components in parallel and because of that; some styles groups are repeated very frequently like Buttons; Grid; Typography etc.
Better to do a common styling first and then everyone use it.
Component API; naming; variable naming; function naming; structural arrangement etc is pain in the ass when everyone goes by their way
While we were refactoring; one of the team member did so with Vim and others with Atom/VSCode. And man we always end up fixing the spaces and code beauty complains from Editor.
Use editorconfig and linting and enforce it.
I am pretty sure that as you will start the new refactor; testing will come up. Spend some time; set it up properly and enforce it. Once ignored, always ignored.
It is true that these npm package for literally everything and even battle tested. But before including them, make sure that you really really need them and will save you a looot of effort.
Like a Basic Calendar or Complex; AutoComplete as package or your code yourself etc.
Don't leave the old code behind; it takes forever to cleanup once you are done with refactor.
You have chance to do it right, from beginning. As you make a refactor release; do the documentation of that refactor and while coding components, add a small readme file for the API and function of the component. Storybook is also an awesome way to document the components.
Settle with easy and fast way for asset inclusion. Assets like Fonts, Images, SVGs (inline or as file) etc.
If I were to do it again,
Above things are on top of mind. I will keep adding more things as I recall; as the refactor is now 1 year old 😉; probably I should think about another refactor 😅