---
name: vue2-to-vue3-migration-orchestrator
description: >-
  Coordinate a phased Vue 2 to Vue 3 migration across state, router, UI framework, i18n, dependencies, and tests. Covers core syntax migration (createApp, v-model, .sync, .native, filters, Vue.extend), ecosystem library replacements, and test stack migration (VTU v1 to v2). Triggers: "Vue 2 to Vue 3", "Vue.extend", ".sync", ".native", "filters", "createLocalVue", "VTU v2", "ecosystem migration", "migration plan".
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Vue 2 to Vue 3 Migration Orchestrator

## Overview

Use this skill to run a large Vue migration as a controlled program: core syntax changes, ecosystem library replacements, test stack upgrades, and phase-gated rollout.

## Resources

- Planning template: [migration-planning-template](references/migration-planning-template.md)
- Core syntax patterns: [core-syntax-migration](references/core-syntax-migration.md)
- Ecosystem replacements: [ecosystem-library-replacements](references/ecosystem-library-replacements.md)
- Test stack migration: [test-stack-vtu-migration](references/test-stack-vtu-migration.md)
- Recommended working copy: `VUE3_MIGRATION_PLAN.md` in target repo root

## Recommended Track Order

1. `pinia-bootstrap-and-outside-component-usage`
2. `vuex-module-to-pinia-store` (includes map helpers and commit/dispatch)
3. `vuex-redux-saga-integration-to-pinia-effects`
4. Core syntax migration (this skill)
5. `lifecycle-reactivity-migration`
6. `vue-router3-to-router4`
7. `vue-i18n8-to-v9`
8. `vuetify2-to-vuetify3`
9. Ecosystem library replacements (this skill)
10. Test stack migration (this skill)

## Phase Plan with Gates

### Phase 0 - Baseline and Safety Net

- **Goal**: establish current behavior baseline.
- **Exit**: build/test baseline captured, critical journeys documented, rollback branch prepared.

### Phase 1 - Runtime Foundation

- **Goal**: Vue 3 app bootstrap and plugin wiring ready.
- **Exit**: app boots under Vue 3, migration mode decided (`@vue/compat` or direct).
- **Rollback**: revert bootstrap changes to last tagged baseline.

### Phase 2 - State Migration

- **Goal**: Pinia runs in parallel, first domain migrated end-to-end.
- **Exit**: Pinia installed, at least one Vuex module removed.
- **Rollback**: disable migrated domain via feature flag, restore Vuex path.

### Phase 3 - Core Syntax and Reactivity

- **Goal**: remove Vue 2-only component APIs.
- **High-priority changes**:
  - `new Vue(...)` → `createApp(...)`
  - `Vue.extend(...)` → `defineComponent(...)`
  - `v-model` contract → `modelValue` + `update:modelValue`
  - `.sync` → `v-model:propName`
  - `v-on.native` removed
  - `$listeners` merged into `$attrs`
  - Filters removed → methods/computed/composables
  - Deprecated slot syntax → `v-slot`
- **Exit**: no `Vue.extend`, `.sync`, `.native`, filters in migrated scope.
- **Rollback**: revert affected component batches by domain.

### Phase 4 - Router and I18n

- **Goal**: Vue Router 4 and vue-i18n v9 APIs stable.
- **Exit**: guards validated, locale switching validated, navigation passes smoke tests.
- **Rollback**: revert router/i18n batch commit.

### Phase 5 - UI Framework and Ecosystem Libraries

- **Goal**: Vuetify 3 and Vue 2-only libraries replaced.
- **Replacement matrix**:

| Vue 2 package | Vue 3 replacement |
|---|---|
| `@gtm-support/vue2-gtm` | `@gtm-support/vue-gtm` |
| `@fingerprintjs/fingerprintjs-pro-vue-v2` | `@fingerprintjs/fingerprintjs-pro-vue-v3` |
| `@iconify/vue2` | `@iconify/vue` |
| `vuedraggable` (v2) | `vuedraggable@next` / `vue.draggable.next` |
| `vue2-editor` | `@vueup/vue-quill` or alternative |

- **Exit**: no Vue 2-only package imports remain, no peer-dependency warnings.
- **Rollback**: revert UI/lib migration slice by feature area.

### Phase 6 - Test Stack and Hardening

- **Goal**: VTU v2 migration completed, CI green.
- **Key breaking changes**:
  - `createLocalVue` removed
  - `propsData` → `props`
  - `mocks`/`stubs` moved under `global`
  - `destroy()` → `unmount()`
  - `scopedSlots` merged into `slots`
  - `findAll().at(i)` → `findAll()[i]`
- **Mount pattern**:
  ```ts
  const wrapper = mount(Component, {
    props: { id: "123" },
    global: {
      plugins: [pinia, router, i18n, vuetify],
      stubs: { Teleport: true },
      mocks: { $t: (k: string) => k },
    },
  })
  ```
- **Exit**: no `createLocalVue` patterns, CI green, critical regression suite green.
- **Rollback**: roll back test harness changes in smallest possible slice.

### Phase 7 - Decommission and Cleanup

- **Goal**: remove temporary bridges and legacy dependencies.
- **Exit**: Vuex removed, compat mode removed, legacy packages removed, docs updated.

## Checkpoint Template (Per Phase)

- Scope shipped
- Validation run (build, tests, smoke journeys)
- Known risks and owners
- Rollback procedure tested (`yes/no`)
- Decision: `go`, `go-with-guard`, or `stop`

## Rollback Rules

- Always rollback by phase slice, never by ad-hoc file edits.
- Keep rollback commits reversible and isolated.
- Prefer feature flags for domain cutovers where possible.
- Do not start next phase until current phase has a `go` checkpoint.

## Common Pitfalls

- Running too many migration tracks in parallel without gates.
- Removing Vuex/compat before side-effect and guard paths are stable.
- Declaring migration complete before cleanup and rollback drills.
- Mixing old and new `v-model` conventions in shared components.
- Removing compat too early before dependency upgrades.
- Replacing package version without updating usage contracts.
- Ignoring archived/unmaintained migration targets.
- Migrating runner and VTU simultaneously without staged validation.
- Assuming VTU v1 shallow slot behavior still applies in v2.
