A client's admin panel had accumulated years of jQuery plugins — a date picker here, a custom dropdown there — each wired directly into specific DOM elements with no consistent pattern, before we could start migrating it to Vue as planned. Untangling it took longer than the Vue rebuild itself, which was not the outcome we had originally scoped the project around.
The main issue was that several jQuery plugins mutated the DOM in ways that would conflict badly with Vue's own virtual DOM diffing if left in place during a gradual migration. A jQuery date picker, for instance, inserts its own markup directly into the page outside of whatever framework is managing that part of the DOM, and if Vue is simultaneously trying to manage and re-render that same region based on its own internal state, the two approaches actively fight each other in ways that produced genuinely confusing bugs during our early attempts at a gradual, side-by-side migration.
Why we ended up doing a harder cutover
We ended up doing a harder cutover than we would have preferred, replacing jQuery plugin instances with Vue-native equivalents screen by screen rather than trying to run both side by side. This meant a given screen was either fully jQuery or fully Vue at any point in time, never a mix, which was slower in terms of overall migration pace but far more reliable than the alternative, and avoided an entire category of DOM-conflict bugs that had eaten disproportionate debugging time in our earlier, more incremental attempts.
The lesson for future projects: when jQuery is going to be replaced eventually, keeping plugin usage isolated and well-documented from the start makes that future migration a straightforward, mechanical process instead of an archaeology project. We now note this explicitly during any new project's initial architecture review — even a project with no current plans to migrate off jQuery benefits from keeping plugin usage isolated, purely as insurance against exactly this situation showing up again on a future client engagement.
How we scoped the cleanup work honestly
The original project estimate treated the jQuery cleanup as a small preliminary step ahead of "the real work" of the Vue rebuild, which in hindsight undersold how much genuine complexity was hiding in years of undocumented plugin usage. We revised our estimation approach for future migrations of this kind to include a dedicated discovery phase — a few days specifically spent cataloging every third-party script and plugin actually in use, and how each one touches the DOM — before committing to a fixed estimate for the rebuild itself, rather than assuming the cleanup work would be trivial purely because it was not the headline deliverable the client was asking for.
What we now document for every new project preemptively
Even on projects with no jQuery in sight and no planned framework migration, we now keep a short running document listing every third-party script included on a client's site, what it does, and which specific elements or features depend on it. It is a small amount of ongoing overhead compared to the alternative of reconstructing that same information under time pressure years later, once whoever originally added a given script has moved on and the only remaining evidence is the script tag itself.