Guided Tutorials
Refactor Legacy jQuery to Modern Framework
Migrate jQuery code to a modern framework while preserving all existing behavior and test coverage. This tutorial uses vanilla JavaScript with modern DOM APIs as the target, but the same approach applies when targeting Vue, React, or any other framework.
What you'll learn
- How to audit a codebase for jQuery usage and categorize each occurrence
- How to replace jQuery DOM manipulation, events, and AJAX with modern APIs
- How to handle edge cases like animations, plugins, and implicit iteration
- How to migrate file by file with test verification after each step
Before you start
- Autohand Code installed. Run
autohand --versionto confirm. See Your First Autohand Session if you need to install it. - A project with jQuery. This tutorial works on any codebase using jQuery 1.x, 2.x, or 3.x.
- Existing tests, if any. Even basic smoke tests will help you verify the refactoring did not change behavior.
- Git with a clean working tree. Run
git stashor commit any changes before starting so you can diff the results clearly.
Assess the jQuery codebase
Before touching any code, get a clear picture of what jQuery is doing in the project. Some usages are straightforward to replace; others need more thought.
Ask Autohand to map out the jQuery usage:
A typical output looks like this:
This inventory tells you where to focus. DOM selection and event binding are trivial to replace. AJAX calls using $.ajax map directly to fetch. Animations require the most judgment since jQuery animations have no direct equivalent without a library.
Tip: Start with files that only use DOM selection and event binding. Leave files with complex animations or plugins for last.
Run the refactoring prompt
Pick a single file to start with. Isolated files with no jQuery plugins are the easiest entry point.
Autohand will read the file, identify every jQuery call, and produce a refactored version. The response includes an explanation of each substitution so you understand what changed and why.
For files that have AJAX calls, use a more targeted prompt:
Review the changes
Autohand produces a side-by-side comparison in its output. Here is what a typical DOM manipulation replacement looks like.
Before (jQuery):
After (vanilla JS):
For AJAX, the replacement is equally direct:
Before:
After:
Verify behavior is preserved
After applying each file's changes, run your test suite immediately. Do not batch multiple files and run tests once at the end.
If tests pass, commit that file before moving to the next one. This keeps your git history clean and makes any regression easy to bisect.
Tip: If you have no automated tests, open the page in a browser after each file and manually exercise the interactions the file handles. Click buttons, submit forms, check that animations still occur. Write down what you checked so you do not forget between files.
Handle edge cases
Some jQuery patterns need extra attention. The three most common ones you will encounter are animation replacements, plugin dependencies, and implicit iteration.
jQuery animations
jQuery's fadeIn, fadeOut, and slideDown have no direct vanilla equivalent. The cleanest replacement is a CSS transition paired with a class toggle:
Ask Autohand to handle this for you:
jQuery plugins
If your code uses third-party jQuery plugins like Select2, Flatpickr (old versions), or DataTables, you have two options: replace them with framework-independent equivalents, or keep the plugin and only remove the jQuery wrapping code around it.
Implicit iteration
jQuery silently applies operations to all matched elements. Vanilla JS requires explicit iteration:
Autohand handles this automatically when refactoring, but it is useful to know when reviewing the output.
Iterate on remaining files
Once you have one or two files done, you have a pattern. Apply it to the rest of the codebase file by file, running tests after each one.
To speed up files that are similar in structure, describe the pattern you established:
When all files are done, check that jQuery is no longer imported anywhere:
If the list is empty, remove jQuery from your dependencies:
Run your full test suite one final time. If everything passes, you are done.
What you learned
- Scanned a codebase and categorized every jQuery usage by type
- Replaced jQuery DOM selection, event binding, and AJAX with modern vanilla JavaScript
- Handled animations with CSS transitions and class toggles instead of jQuery effects
- Migrated file by file with test runs after each change to preserve behavior