` (keeps DOM, toggles `display`) |
| `$.Deferred()` | Native `Promise` / `async`/`await` | `const data = await fetch(url).then(r => r.json())` |
| `$('#plugin').pluginName()` | Custom directive or composable | `app.directive('tooltip', { mounted(el) { ... } })` |
## Decision Tree
```
START
├── Is the jQuery codebase < 500 lines with simple event handling?
│ ├── YES → Skip Vue, replace jQuery calls with vanilla JS (see jquery-to-vanilla-js)
│ └── NO ↓
├── Is this a full rewrite or incremental migration?
│ ├── FULL REWRITE → Scaffold new Vue 3 project (npm create vue@latest), rebuild from scratch
│ └── INCREMENTAL ↓
├── Does the page have isolated UI widgets (modals, tabs, forms)?
│ ├── YES → Start with "Vue Islands": mount Vue apps into existing page via createApp().mount()
│ └── NO ↓
├── Does the jQuery code heavily mutate shared global state (window.appState, data-* attrs)?
│ ├── YES → First extract state into a Pinia store or provide/inject, then migrate UI
│ └── NO ↓
├── Are there jQuery plugins with no Vue equivalent?
│ ├── YES → Wrap them in a custom directive using mounted/unmounted hooks (see Step 6)
│ └── NO ↓
├── Is the app server-rendered (PHP, Rails, Django templates)?
│ ├── YES → Use Vue's in-DOM template mode: createApp with existing HTML as template
│ └── NO ↓
└── DEFAULT → Migrate page-by-page: replace jQuery selectors with Vue components, use v-model for forms, replace $.ajax with fetch/composables
```
## Decision Logic
Structured if/then rules for agent-driven recommendations. Each rule maps a concrete migration condition to an action.
### If the jQuery codebase is under 500 lines with only simple event handlers
--> Skip Vue entirely; replace jQuery calls with vanilla JS (`querySelector`, `addEventListener`, `fetch`). [src3]
### If you need a no-build-step incremental migration on a server-rendered page (PHP, Rails, Django)
--> Load Vue 3 via CDN (`vue.global.prod.js`) and mount widgets with `createApp(...).mount('#id')`; the full build is required because in-DOM templates need the compiler. [src1, src4]
### If the page has isolated UI widgets (modals, tabs, forms) embedded in jQuery
--> Migrate as "Vue Islands": mount one `createApp()` per widget into its own container, leave the rest to jQuery, and remove jQuery only after every island is migrated. [src1, src4]
### If jQuery code stores shared state in the DOM (`data-*` attrs, hidden inputs, classes)
--> Extract that implicit state into a Pinia store or a shared `reactive()` bridge object first, then migrate the UI on top of it. [src4]
### If the app depends on a jQuery plugin with no Vue equivalent (date picker, rich-text editor, chart)
--> Wrap the plugin in a Vue custom directive, init in `mounted`, sync in `updated`, and always `destroy` in `unmounted` to prevent leaks. [src5, src8]
### If you are starting a green-field rewrite and want maximum runtime performance
--> Scaffold with `npm create vue@latest` on Vue 3.5 (stable), and evaluate Vue 3.6 Vapor Mode (`
```
**Verify**: `import { createApp } from 'vue'` compiles without errors, or `window.Vue` is available in the browser console.
### 3. Create mount points and mount Vue apps
Add container elements where Vue will take over. jQuery continues managing everything else on the page. Vue 3 supports multiple independent app instances on one page. [src1, src4]
```html
```
```javascript
// mount-search.js -- mount Vue into existing page
import { createApp, ref } from 'vue';
const SearchWidget = {
setup() {
const query = ref('');
const results = ref([]);
async function search() {
const res = await fetch(`/api/search?q=${encodeURIComponent(query.value)}`);
results.value = await res.json();
}
return { query, results, search };
},
template: `
`
};
const container = document.getElementById('vue-search-widget');
if (container) {
createApp(SearchWidget).mount(container);
}
```
**Verify**: The Vue component renders within the existing page layout without breaking jQuery functionality. Inspect the mount element -- it should contain Vue-rendered DOM.
### 4. Replace jQuery DOM manipulation with Vue reactive state
Convert imperative DOM updates to declarative Vue state using `ref()` and `reactive()`. This is the core of the migration -- stop reading from the DOM and let Vue's reactivity system drive UI updates. Vue 3.5 improved reactivity memory usage by 56%. [src2, src3, src6]
```javascript
// BEFORE: jQuery
let count = 0;
$('#counter').text(count);
$('#increment').on('click', function() {
count++;
$('#counter').text(count);
});
// AFTER: Vue 3 Composition API
import { createApp, ref } from 'vue';
const Counter = {
setup() {
const count = ref(0);
const increment = () => count.value++;
return { count, increment };
},
template: `
{{ count }}
`
};
createApp(Counter).mount('#counter-mount');
```
**Verify**: Remove the jQuery code for that widget, confirm the Vue version renders and behaves identically. Check Vue DevTools -- state should be reactive.
### 5. Replace $.ajax with fetch or a Vue composable
Convert AJAX calls to the modern fetch API wrapped in a reusable composable. Composables are Vue's equivalent of React hooks -- reusable stateful logic extracted into functions. Use `onWatcherCleanup()` (Vue 3.5+) for automatic request cancellation inside watchers. [src3, src6]
```javascript
// composables/useFetch.js -- reusable data fetching composable
import { ref, onMounted, onUnmounted } from 'vue';
export function useFetch(url) {
const data = ref(null);
const error = ref(null);
const loading = ref(true);
let controller = null;
async function fetchData() {
controller = new AbortController();
loading.value = true;
error.value = null;
try {
const res = await fetch(url, { signal: controller.signal });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
data.value = await res.json();
} catch (err) {
if (err.name !== 'AbortError') error.value = err.message;
} finally {
loading.value = false;
}
}
onMounted(fetchData);
onUnmounted(() => controller?.abort());
return { data, error, loading, refetch: fetchData };
}
// Usage in a component
const UserList = {
setup() {
const { data: users, loading, error } = useFetch('/api/users');
return { users, loading, error };
},
template: `
Loading...
Error: {{ error }}
`
};
```
**Verify**: Network tab shows the same API requests. Compare response handling with the old jQuery version. Unmounting the component should abort in-flight requests.
### 6. Wrap jQuery plugins using custom directives
For plugins without Vue alternatives (date pickers, rich text editors, legacy charting libraries), wrap them in a Vue custom directive using the `mounted` and `unmounted` lifecycle hooks. [src5, src8]
```javascript
// directives/v-chosen.js -- wraps jQuery Chosen plugin
import $ from 'jquery';
import 'chosen-js';
export const vChosen = {
mounted(el, binding) {
const $el = $(el);
$el.chosen({ width: '100%', ...binding.value });
// Sync changes back to Vue
$el.on('change', () => {
el.dispatchEvent(new Event('change'));
});
},
updated(el) {
$(el).trigger('chosen:updated');
},
unmounted(el) {
$(el).chosen('destroy');
}
};
// Register globally
import { createApp } from 'vue';
const app = createApp(App);
app.directive('chosen', vChosen);
app.mount('#app');
// Use in template
//
```
**Verify**: Plugin initializes on mount, updates when Vue state changes, and destroys cleanly on unmount. Check browser console for errors and memory leaks via DevTools heap snapshot.
### 7. Remove jQuery and clean up
Once all components are migrated and no code references jQuery, uninstall it and remove all script tags. If migrating from jQuery 3.x, consider whether jQuery 4.0 compatibility changes affect your remaining code. [src3, src4, src7]
```bash
# Uninstall jQuery
npm uninstall jquery
# Remove from HTML
# <- delete this line
# Search for any remaining $ or jQuery references
grep -rn '\$(\|jQuery(' --include='*.js' --include='*.vue' --include='*.html'
# Check your bundler output for jQuery
npx vite build --mode production 2>&1 | grep -i jquery
```
**Verify**: `grep -rn 'jquery' --include='*.json' --include='*.js' --include='*.vue'` returns zero results. The application runs without jQuery loaded. Bundle size should decrease by ~19.5-30 KB (gzipped, depending on jQuery version).
## Code Examples
### JavaScript/Vue 3: Full page migration from jQuery to Vue SFC
> Full script: [javascript-vue-3-full-page-migration-from-jquery-t.js](scripts/javascript-vue-3-full-page-migration-from-jquery-t.js) (46 lines)
```javascript
// Input: A jQuery page with a search form, results list, and loading spinner
// Output: Equivalent Vue 3 Single File Component with Composition API
// SearchPage.vue