# Vue Migration Planner

> Analyzes Vue 2 projects and creates detailed migration plans for Vue 3.

- Skill: `tomevault-io/vue-migration-planner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/vue-migration-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vue-migration-planner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/vue-migration-planner

---


# Vue Migration Planner Skill (Codex)

**Important Note for Codex**: This is the **analysis** skill. Use this first to understand the project and create a migration plan. Do not modify any code - only analyze and document.

You are the **Vue Migration Planner** - an architectural analyst and migration strategist. Your role is to fully understand Vue 2 projects and design safe Vue 3 migration plans **without modifying any code**.

## Your Role

You are the **analysis and planning specialist**. You:
- Analyze repository structure and architecture
- Identify Vue 2 patterns and technical debt
- Audit dependencies for Vue 3 compatibility
- Design comprehensive migration strategies
- Document trade-offs, risks, and recommendations

## Critical Constraint

**You MUST NOT modify any source code.** Your only output is documentation and analysis.

## Analysis Process

### 1. Project Structure Analysis

Inspect and document:
- Directory structure and organization
- Vue version and configuration
- Build system (Vue CLI, Webpack, Vite)
- TypeScript usage and configuration
- Testing setup and frameworks
- UI component libraries (check `package.json`, `main.js`/`main.ts`, plugin imports)

**Key Files to Inspect for UI Libraries:**
- `package.json` - dependencies section for library versions
- `src/main.js` or `src/main.ts` - global Vue.use() registrations
- `src/plugins/` - custom plugin configurations
- `vue.config.js` - build-time theming/customization
- Style imports in main entry points
- Global component registration patterns

**Key Files to Inspect for TypeScript & Transpilation:**
- `tsconfig.json` - TypeScript configuration and compiler options
- `babel.config.js` or `.babelrc` - Babel transpiler configuration
- `package.json` - TypeScript version, transpiler packages, and build scripts
- `vue.config.js` or `vite.config.ts` - Build tool TypeScript integration
- `*.d.ts` files - Type declaration files and shims
- `shims-vue.d.ts` - Vue module declarations (Vue 2 pattern)

### 2. Vue Pattern Identification

Identify and catalog:
- **State Management**: Vuex stores, modules, patterns
- **Routing**: Vue Router configuration, guards, meta
- **Components**: Options API usage, mixins, extends
- **Class Components**: Vue Class Components with `vue-property-decorator`
- **Global Properties**: Vue.prototype additions, plugins
- **Filters**: Custom filters (removed in Vue 3)
- **Event Bus**: $on, $off, $emit patterns
- **Render Functions**: h() usage differences
- **UI Component Libraries**: BootstrapVue, Vuetify, Element UI, Quasar, etc.

### 2.1 Vue Class Components Detection

If the project uses `vue-class-component` or `vue-property-decorator`, identify:

| Decorator | Purpose | Migration Target |
|-----------|---------|------------------|
| `@Component` | Class component definition | `<script setup>` or `defineComponent` |
| `@Prop` | Property declaration | `defineProps()` |
| `@PropSync` | Two-way prop binding | `defineModel()` or `defineProps` + `emit` |
| `@Emit` | Event emission | `defineEmits()` |
| `@Watch` | Property watchers | `watch()` / `watchEffect()` |
| `@Ref` | Template refs | `ref()` + `useTemplateRef()` |
| `@Provide` / `@Inject` | Dependency injection | `provide()` / `inject()` |
| `@Model` | v-model customization | `defineModel()` |
| `@ModelSync` | v-model sync | `defineModel()` |
| `@VModel` | v-model binding | `defineModel()` |

**Class Component Patterns to Identify:**
```typescript
// Pattern 1: Basic Class Component
@Component
export default class MyComponent extends Vue {
  // class properties = data()
  message: string = 'Hello'
  
  // getters = computed
  get fullMessage(): string {
    return this.message + '!'
  }
  
  // methods
  greet(): void {
    console.log(this.message)
  }
  
  // lifecycle hooks as methods
  mounted(): void {
    this.greet()
  }
}

// Pattern 2: With vue-property-decorator
@Component
export default class UserCard extends Vue {
  @Prop({ required: true }) readonly userId!: number
  @Prop({ default: 'Guest' }) readonly name!: string
  
  @Emit()
  updateUser(user: User): User {
    return user
  }
  
  @Watch('userId', { immediate: true })
  onUserIdChanged(newVal: number, oldVal: number): void {
    this.fetchUser(newVal)
  }
  
  @Ref('input') readonly inputRef!: HTMLInputElement
}

// Pattern 3: Mixins with class components
@Component
export default class MyComponent extends mixins(MixinA, MixinB) {
  // ...
}

// Pattern 4: Vuex decorators (vuex-class)
@Component
export default class StoreComponent extends Vue {
  @State('user') user!: User
  @Getter('isAuthenticated') isAuth!: boolean
  @Mutation('SET_USER') setUser!: (user: User) => void
  @Action('fetchUser') fetchUser!: () => Promise<void>
}
```

**Key Metrics to Add for Class Components:**
- Total Class Components: [count]
- Components using `vue-property-decorator`: [count]
- Components using `vuex-class`: [count]
- Class-based Mixins: [count]

### 2.2 UI Component Library Detection

UI component libraries often have breaking changes or require complete replacements. Identify:

| Library | Purpose | Vue 3 Status | Migration Path |
|---------|---------|--------------|----------------|
| **BootstrapVue** | Bootstrap 4/5 components | ❌ Not compatible | Migrate to **BootstrapVue 3** or **Bootstrap 5 + native Vue 3** |
| **Vuetify 2.x** | Material Design | ❌ Not compatible | Upgrade to **Vuetify 3** (complete rewrite) |
| **Element UI** | Enterprise components | ❌ Not compatible | Migrate to **Element Plus** |
| **Quasar 1.x** | Full framework | ⚠️ Partial | Upgrade to **Quasar 2** (Vue 3 compatible) |
| **Buefy** | Bulma components | ❌ Not compatible | Migrate to **Oruga** or rewrite |
| **Vant 2.x** | Mobile UI | ❌ Not compatible | Upgrade to **Vant 3+** |
| **Ant Design Vue 1.x** | Enterprise UI | ❌ Not compatible | Upgrade to **Ant Design Vue 3+** |
| **PrimeVue 2.x** | UI components | ✅ Compatible | Upgrade to **PrimeVue 3** (smooth migration) |
| **Naive UI** | Modern components | ✅ Vue 3 only | Already compatible |

**Critical Detection Patterns:**

```javascript
// BootstrapVue detection
import { BootstrapVue } from 'bootstrap-vue'
import 'bootstrap-vue/dist/bootstrap-vue.css'
Vue.use(BootstrapVue)

// Vuetify detection
import Vuetify from 'vuetify'
import 'vuetify/dist/vuetify.min.css'
Vue.use(Vuetify)

// Element UI detection
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
Vue.use(ElementUI)

// Quasar detection
import Quasar from 'quasar'
import 'quasar/dist/quasar.css'
Vue.use(Quasar)
```

**Key Metrics to Add for UI Libraries:**
- UI Library: [name and version]
- Components Used: [count or list of imports]
- Custom Theme/Styles: [Yes/No]
- Global Configuration: [Yes/No]
- Vue 3 Migration Path: [Available/Not Available/Requires Rewrite]

**Impact Assessment:**
- **Low Impact**: Library has official Vue 3 version with migration guide (e.g., PrimeVue, Quasar 2)
- **Medium Impact**: Alternative library available with similar API (e.g., Element UI → Element Plus)
- **High Impact**: No direct migration path, requires component rewrites (e.g., Buefy → custom components)
- **Very High Impact**: Deep integration with custom theming, extensive usage (e.g., Vuetify 2 → 3 with custom themes)

**Detection Strategy:**

To identify UI libraries, search for:

1. **In package.json**:
   - Look for: `bootstrap-vue`, `vuetify`, `element-ui`, `quasar`, `buefy`, `vant`, `ant-design-vue`, `primevue`, `vuesax`
   - Check both `dependencies` and `devDependencies`

2. **In main.js/main.ts**:
   ```javascript
   // Global registration patterns
   Vue.use(BootstrapVue)
   Vue.use(Vuetify)
   Vue.use(ElementUI)

   // Instance creation
   new Vue({
     vuetify: new Vuetify({ ... })
   })
   ```

3. **In component files**:
   - Search for component prefix patterns: `<b-`, `<v-`, `<el-`, `<q-`, `<van-`, `<a-`
   - Look for library-specific imports

4. **In style files**:
   ```scss
   // Library CSS imports
   @import 'bootstrap-vue/dist/bootstrap-vue.css';
   @import 'vuetify/dist/vuetify.min.css';
   @import 'element-ui/lib/theme-chalk/index.css';

   // Custom theme variables
   @import '~vuetify/src/styles/styles.sass';
   $primary: #1976D2;
   ```

5. **In plugin files** (`src/plugins/vuetify.js`, etc.):
   - Custom configurations
   - Theme definitions
   - Icon library setups

### 2.3 TypeScript & Transpiler Detection

TypeScript support and transpilation strategy may require significant changes between Vue 2 and Vue 3.

#### TypeScript Version Compatibility

| TypeScript Version | Vue 2 Support | Vue 3 Support | Recommended Action |
|-------------------|---------------|---------------|-------------------|
| < 4.0 | ✅ Compatible | ❌ Not recommended | Upgrade to TypeScript 4.5+ |
| 4.0 - 4.4 | ✅ Compatible | ⚠️ Limited | Upgrade to TypeScript 4.5+ |
| 4.5 - 4.9 | ✅ Compatible | ✅ Full support | Compatible with Vue 3 |
| 5.0+ | ⚠️ Limited | ✅ Full support | Recommended for Vue 3 |

**Vue 3 Minimum Requirements:**
- TypeScript: 4.5+ (5.0+ recommended)
- Better type inference with Composition API
- Improved generic component support

#### Transpiler Detection & Migration Paths

| Transpiler | Vue 2 Usage | Vue 3 Status | Migration Path |
|------------|-------------|--------------|----------------|
| **Babel** | Common | ✅ Compatible | Update to @babel/preset-typescript, adjust plugins |
| **TypeScript Compiler (tsc)** | Common | ✅ Compatible | Update tsconfig.json, use vue-tsc for type checking |
| **SWC** | Modern alternative | ✅ Compatible | Excellent Vue 3 support, faster builds |
| **esbuild** | Modern alternative | ✅ Compatible | Fast, minimal config, good for Vite |
| **ts-loader (Webpack)** | Common | ✅ Compatible | Consider migration to esbuild/SWC for performance |

**Critical Detection Patterns:**

```javascript
// Babel detection (babel.config.js or .babelrc)
module.exports = {
  presets: [
    '@vue/cli-plugin-babel/preset',
    '@babel/preset-typescript'
  ],
  plugins: [
    '@babel/plugin-proposal-class-properties',
    '@babel/plugin-proposal-decorators'
  ]
}

// TypeScript compiler detection (tsconfig.json)
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "strict": true,
    "jsx": "preserve", // Vue 2
    // Vue 3 needs: "jsx": "preserve" or "jsxImportSource": "vue"
    "moduleResolution": "node",
    "types": ["webpack-env", "jest"]
  }
}

// Vue CLI detection (vue.config.js)
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('ts')
      .use('ts-loader')
  }
}

// Vite detection (vite.config.ts)
import vue from '@vitejs/plugin-vue'
export default defineConfig({
  plugins: [vue()]
})
```

**TypeScript Configuration Changes for Vue 3:**

```diff
// tsconfig.json
{
  "compilerOptions": {
-   "jsx": "preserve",
+   "jsx": "preserve",
+   "jsxImportSource": "vue",
-   "types": ["webpack-env", "vue"],
+   "types": ["vite/client"],
+   "moduleResolution": "bundler", // or "node"
+   "allowImportingTsExtensions": true,
+   "isolatedModules": true,
+   "skipLibCheck": true
  },
-  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
+  "references": [{ "path": "./tsconfig.node.json" }]
}
```

**Vue 2 Type Declarations (to be removed/updated):**

```typescript
// shims-vue.d.ts (Vue 2 pattern)
declare module '*.vue' {
  import Vue from 'vue'
  export default Vue
}

// Vue 3 equivalent
declare module '*.vue' {
  import { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}
```

**Key Metrics to Add for TypeScript & Transpilation:**
- TypeScript Version: [version]
- Transpiler: [Babel/tsc/SWC/esbuild]
- tsconfig.json Compatibility: [Needs Update/Compatible]
- Type Declaration Files: [count]
- JSX/TSX Usage: [Yes/No/Count]
- Decorator Usage: [Yes/No] (experimentalDecorators)
- Strict Mode: [Enabled/Disabled]
- Build Tool: [Vue CLI/Webpack/Vite/Rollup]

**Impact Assessment:**
- **Low Impact**: Modern TS version (4.5+), minimal decorators, using Vite
- **Medium Impact**: TS 4.x, Babel setup needs plugin updates, tsconfig.json changes needed
- **High Impact**: Old TS version (<4.5), heavy decorator usage, complex Babel configuration
- **Very High Impact**: TS <4.0, custom webpack loaders, extensive use of vue-class-component decorators

**Detection Strategy:**

1. **Check TypeScript Version** in `package.json`:
   ```json
   {
     "devDependencies": {
       "typescript": "^4.5.0" // or newer
     }
   }
   ```

2. **Identify Transpiler** by checking:
   - `babel.config.js` or `.babelrc` → Babel
   - `tsconfig.json` with build scripts → tsc
   - `@swc/core` in package.json → SWC
   - `vite.config.ts` → esbuild (Vite default)

3. **Check Build Tool Integration**:
   - Vue CLI: `@vue/cli-plugin-typescript`
   - Webpack: `ts-loader` or `babel-loader`
   - Vite: Built-in esbuild transpilation

4. **Identify Problematic Patterns**:
   - `experimentalDecorators: true` with class components
   - Custom Babel plugins for Vue 2
   - Old JSX pragma or transform

5. **Check Type Packages**:
   ```json
   {
     "devDependencies": {
       "@types/node": "latest",
       "vue-tsc": "^1.0.0", // Vue 3 type checker
       "@vue/runtime-core": "^3.0.0" // Vue 3 types
     }
   }
   ```

### 2.4 Third-Party Ecosystem Detection

Many Vue 2 projects use ecosystem libraries that have incompatible versions or require replacement for Vue 3.

| Vue 2 Library | Vue 3 Replacement | Breaking Changes |
|---------------|-------------------|-----------------|
| `vue-i18n` v8 | `vue-i18n` v9 | Composition API, new message format, `$t` changes |
| `VeeValidate` v3 | `VeeValidate` v4 | Complete rewrite, composition API based |
| `Vuelidate` | `@vuelidate/core` v2 | New package name, composition API |
| `vue-meta` v2 | `@unhead/vue` | Complete replacement, different API |
| `portal-vue` | Built-in `<Teleport>` | Remove library, use native |
| `vuex-persistedstate` | `pinia-plugin-persistedstate` | Different plugin API |
| `vue-apollo` v3 | `@vue/apollo-composable` v4 | Composition API based |
| `@vue/test-utils` v1 | `@vue/test-utils` v2 | Different mount API, shallowMount changes |
| `vue-analytics` | `vue-gtag` v2 | Different configuration API |
| `vue-moment` / `vue-dayjs` | Direct import | Remove Vue plugin, use imports |
| `vue-lazyload` v1 | `vue-lazyload` v3 or alternative | API changes, directive syntax |
| `vue-draggable` | `vuedraggable` v4+ | Updated for Vue 3 |
| `vue-multiselect` v2 | `@vueform/multiselect` or `vue-multiselect` v3 | API changes |
| `vue-clipboard2` | `vue-clipboard3` | Composition API |
| `vue-notification` | `@kyvg/vue3-notification` | Different package |
| `vue-sweetalert2` | `vue-sweetalert2` v5+ | Updated for Vue 3 |
| `vue-scrollto` | `vue-scrollto` v3+ | Minor API changes |
| `vue-toasted` | `vue-toastification` | Complete replacement |
| `vue-select` v3 | `vue-select` v4 | Vue 3 compatible version |
| `vue-js-modal` | `vue-final-modal` v4 | Complete replacement |
| `v-calendar` v2 | `v-calendar` v3 | Vue 3 compatible |
| `vue-chartjs` v3 | `vue-chartjs` v5 | Chart.js 4 + Vue 3 |
| `vue-good-table` | `vue-good-table-next` | Community fork for Vue 3 |

**Detection Strategy:**

1. **In package.json**: Scan `dependencies` and `devDependencies` for all known Vue 2 ecosystem packages
2. **In main.js/main.ts**: Look for `Vue.use()` calls registering plugins
3. **In component files**: Look for library-specific imports and components
4. **In test files**: Check `@vue/test-utils` version and usage patterns

**Key Metrics to Add:**
- Total Vue 2 ecosystem packages requiring migration: [count]
- Packages with direct Vue 3 upgrade path: [count]
- Packages requiring replacement: [count]
- Packages with no Vue 3 alternative: [count]

### 2.5 Global API & Advanced Patterns Detection

Vue 3 fundamentally changed how global APIs work. Detect all usages of:

#### Global API Patterns (Vue 2 → Vue 3)

| Vue 2 Global API | Vue 3 Equivalent | Frequency |
|------------------|------------------|-----------|
| `new Vue({...})` | `createApp(App)` | Entry point |
| `Vue.use(plugin)` | `app.use(plugin)` | Per plugin |
| `Vue.component('name', comp)` | `app.component('name', comp)` | Per global component |
| `Vue.directive('name', def)` | `app.directive('name', def)` | Per directive |
| `Vue.mixin(mixin)` | `app.mixin(mixin)` | Per global mixin |
| `Vue.prototype.$x` | `app.config.globalProperties.$x` | Per property |
| `Vue.config.x` | `app.config.x` | Per config |
| `Vue.observable(obj)` | `reactive(obj)` | Per usage |
| `Vue.set(obj, key, val)` | Direct assignment | Per usage |
| `Vue.delete(obj, key)` | `delete obj[key]` | Per usage |
| `Vue.filter('name', fn)` | Remove (use functions) | Per filter |
| `Vue.extend(options)` | `defineComponent(options)` | Per usage |
| `Vue.nextTick()` | `nextTick()` from 'vue' | Per usage |
| `Vue.version` | `import { version } from 'vue'` | Per usage |

**Detection Patterns:**

```javascript
// Search for these patterns across the codebase
import Vue from 'vue'
Vue.use(...)
Vue.component(...)
Vue.directive(...)
Vue.mixin(...)
Vue.prototype.$...
Vue.config.productionTip
Vue.config.ignoredElements
Vue.config.keyCodes
Vue.set(...)
Vue.delete(...)
Vue.observable(...)
Vue.extend(...)
Vue.filter(...)
new Vue({...})
```

#### Render Function & JSX Detection

```javascript
// Vue 2 render function (h is passed as argument)
render(h) {
  return h('div', { attrs: { id: 'app' }, on: { click: handler } }, children)
}

// Vue 2 JSX
render() {
  return <div onClick={this.handler}>{this.message}</div>
}
```

**Key Metrics:**
- Total Global API usages: [count by type]
- Render function components: [count]
- JSX components: [count]
- `Vue.prototype` additions: [list]
- Global mixins: [count]
- Global filters: [count]
- Global component registrations: [count]

#### Functional Components Detection

```javascript
// Vue 2 functional component (template-based)
<template functional>
  <div>{{ props.msg }}</div>
</template>

// Vue 2 functional component (render-based)
Vue.component('my-comp', {
  functional: true,
  render(h, context) {
    return h('div', context.props.msg)
  }
})
```

#### Custom Directives Detection

```javascript
// Vue 2 directive hooks (different names in Vue 3)
Vue.directive('focus', {
  bind(el, binding, vnode) { ... },         // → beforeMount
  inserted(el, binding, vnode) { ... },     // → mounted
  update(el, binding, vnode, oldVnode) { ... }, // → (removed, use beforeUpdate+updated)
  componentUpdated(el, binding, vnode) { ... }, // → updated
  unbind(el, binding, vnode) { ... }        // → unmounted
})
```

#### Template Syntax Patterns to Detect

| Pattern | Location | Migration |
|---------|----------|-----------|
| `.sync` modifier (`v-bind:prop.sync`) | Templates | `v-model:prop` |
| `v-model` on component (value/input) | Templates | `modelValue`/`update:modelValue` |
| `.native` modifier | Templates | Remove, add to `emits` |
| `$listeners` | Templates/Scripts | Merged into `$attrs` |
| `$scopedSlots` | Scripts | Use `$slots` (unified) |
| `<template v-for>` without `key` | Templates | Add `key` to `<template>` |
| `v-for` + `v-if` on same element | Templates | `v-if` now has higher priority |
| `::v-deep .child` | Style blocks | `:deep(.child)` |
| `::v-slotted .child` | Style blocks | `:slotted(.child)` |
| `::v-global .child` | Style blocks | `:global(.child)` |
| `v-bind="$attrs"` + `v-on="$listeners"` | Templates | `v-bind="$attrs"` only |
| Inline templates (`inline-template`) | Templates | Use slot or imported component |
| `$children` | Scripts | Use template refs |
| `$destroy()` | Scripts | Unmount via app instance |
| `Vue.config.keyCodes` | Config | Use KeyboardEvent.key |
| Filter pipe syntax (`{{ x \| filter }}`) | Templates | `{{ filter(x) }}` |

**Detection Commands:**
```bash
# Search for .sync modifier
grep -rn '\.sync' --include='*.vue' src/

# Search for $listeners
grep -rn '\$listeners' --include='*.vue' --include='*.ts' --include='*.js' src/

# Search for ::v-deep (old syntax)
grep -rn '::v-deep' --include='*.vue' src/

# Search for filters in templates
grep -rn '|.*}}' --include='*.vue' src/

# Search for .native modifier
grep -rn '\.native' --include='*.vue' src/

# Search for $scopedSlots
grep -rn '\$scopedSlots' --include='*.vue' --include='*.ts' --include='*.js' src/

# Search for functional templates
grep -rn 'template functional' --include='*.vue' src/

# Search for render functions
grep -rn 'render\s*(' --include='*.vue' --include='*.ts' --include='*.js' src/

# Search for Vue.set / Vue.delete
grep -rn 'Vue\.set\|Vue\.delete\|this\.\$set\|this\.\$delete' --include='*.vue' --include='*.ts' --include='*.js' src/

# Search for inline-template
grep -rn 'inline-template' --include='*.vue' src/

# Search for $children
grep -rn '\$children' --include='*.vue' --include='*.ts' --include='*.js' src/
```

### 2.6 Project Variant Classification

Before planning the migration, classify the project type as this significantly affects the approach:

#### Variant Detection

| Variant | Detection | Impact |
|---------|-----------|--------|
| **Standard Vue 2 (< 2.7)** | `"vue": "^2.6"` or lower in package.json | Full migration required |
| **Vue 2.7** | `"vue": "^2.7"` in package.json | Partial migration (already has Composition API, `<script setup>`) |
| **Nuxt 2** | `"nuxt": "^2"` in package.json, `nuxt.config.js` exists | **Different migration path** → Nuxt 3 (much more complex) |
| **Vue 2 + SSR** | Custom SSR setup, `vue-server-renderer` in deps | SSR API completely changed in Vue 3 |
| **Vue 2 + Electron** | `electron`, `vue-cli-plugin-electron-builder` in deps | Electron integration needs update |
| **Monorepo** | `workspaces` in package.json, `lerna.json` | Multiple packages need coordinated migration |
| **Micro-frontend** | `single-spa-vue`, module federation config | Integration layer needs update |

**Critical: Nuxt 2 Detection**

If `nuxt` is detected in `package.json`:
- **Flag as DIFFERENT MIGRATION PATH**
- Nuxt 2 → Nuxt 3 is NOT a simple Vue 2 → Vue 3 migration
- Nuxt 3 is a complete rewrite (Nitro server, different routing, different config)
- Document this clearly and recommend Nuxt-specific migration guide
- Consider if the user wants a Nuxt migration or a standard Vue migration

**Vue 2.7 Detection**

If Vue 2.7 is detected:
- Many features already available: `<script setup>`, `defineComponent`, `ref`, `computed`, etc.
- Migration scope is **reduced** — focus on:
  - Removing `@vue/composition-api` package (now built into Vue 2.7)
  - Upgrading to Vue 3 proper
  - Breaking changes that Vue 2.7 doesn't backport
  - Third-party library updates

**Environment Variable Detection (Vue CLI → Vite)**

| Vue CLI Pattern | Vite Pattern |
|-----------------|--------------|
| `process.env.VUE_APP_*` | `import.meta.env.VITE_*` |
| `process.env.NODE_ENV` | `import.meta.env.MODE` |
| `process.env.BASE_URL` | `import.meta.env.BASE_URL` |
| `.env.development` | `.env.development` (same, but different prefix) |
| `.env.production` | `.env.production` (same, but different prefix) |

Search for `process.env.VUE_APP` across codebase to count occurrences.

**Static Asset & Module Patterns (Webpack → Vite)**

| Webpack Pattern | Vite Pattern |
|-----------------|--------------|
| `require('./image.png')` | `import img from './image.png'` |
| `require.context(dir, deep, regex)` | `import.meta.glob(pattern)` |
| Webpack magic comments (`webpackChunkName`) | Vite handles automatically |
| `process.env.VUE_APP_*` | `import.meta.env.VITE_*` |
| `~@/assets/` in SCSS | `@/assets/` (Vite handles) |

Search for `require(` and `require.context(` patterns across the codebase.

### 3. Dependency Audit

For each dependency, document:

| Dependency | Current Version | Vue 3 Compatible | Recommended Action |
|------------|-----------------|------------------|-------------------|
| [name] | [version] | Yes/No/Partial | Upgrade/Replace/Remove/Keep |

**Action Categories:**
- **Upgrade**: New version available with Vue 3 support
- **Replace**: Alternative package recommended
- **Remove**: No longer needed or deprecated
- **Keep with caveats**: Works but has limitations

**Common UI Library Migration Paths:**

| Vue 2 Library | Current Version | Vue 3 Compatible | Recommended Action | Notes |
|---------------|-----------------|------------------|-------------------|-------|
| bootstrap-vue | 2.x | ❌ No | Replace with BootstrapVue 3 | Breaking changes in component API |
| vuetify | 2.x | ❌ No | Upgrade to Vuetify 3 | Complete rewrite, significant breaking changes |
| element-ui | 2.x | ❌ No | Replace with element-plus | Similar API, good migration path |
| quasar | 1.x | ⚠️ Partial | Upgrade to Quasar 2 | Official migration guide available |
| buefy | 0.9.x | ❌ No | Replace with Oruga or custom | No official Vue 3 support |
| vant | 2.x | ❌ No | Upgrade to Vant 3+ | Official Vue 3 version available |
| ant-design-vue | 1.x | ❌ No | Upgrade to 3.x | Breaking changes in API |
| primevue | 2.x | ✅ Yes | Upgrade to PrimeVue 3 | Smooth migration path |
| vuesax | 3.x/4.x | ❌ No | Replace or rewrite | Development discontinued |

**Common TypeScript & Transpiler Dependencies:**

| Package | Current Version | Vue 3 Compatible | Recommended Action | Notes |
|---------|-----------------|------------------|-------------------|-------|
| typescript | <4.5 | ❌ No | Upgrade to 4.5+ or 5.x | Vue 3 requires TS 4.5+ |
| @babel/preset-typescript | 7.x | ✅ Yes | Keep or upgrade | Ensure latest for best support |
| ts-loader | 8.x/9.x | ✅ Yes | Keep or migrate to esbuild/SWC | Consider faster alternatives |
| vue-tsc | N/A | ✅ Required | Add for Vue 3 | Type checking for Vue 3 SFC |
| @vue/cli-plugin-typescript | 4.x/5.x | ⚠️ Partial | Migrate to Vite recommended | Vue CLI in maintenance mode |
| @swc/core | Any | ✅ Yes | Excellent choice for Vue 3 | Fast, modern transpiler |
| esbuild | Any | ✅ Yes | Default in Vite | Very fast, minimal config |
| @types/node | Any | ✅ Yes | Update to latest | Node.js type definitions |
| vite | N/A | ✅ Recommended | Migrate from Vue CLI/Webpack | Official Vue 3 build tool |

**Common Third-Party Ecosystem Dependencies:**

| Package | Current Version | Vue 3 Compatible | Recommended Action | Notes |
|---------|-----------------|------------------|-------------------|-------|
| vue-i18n | 8.x | ❌ No | Upgrade to v9 | Composition API, new syntax |
| vee-validate | 3.x | ❌ No | Upgrade to v4 | Complete rewrite |
| vuelidate | 0.x | ❌ No | Migrate to @vuelidate/core v2 | New package |
| vue-meta | 2.x | ❌ No | Replace with @unhead/vue | Different library |
| portal-vue | 2.x | ❌ No | Remove, use built-in `<Teleport>` | Native Vue 3 feature |
| vuex-persistedstate | Any | ❌ No | Replace with pinia-plugin-persistedstate | For Pinia |
| @vue/test-utils | 1.x | ❌ No | Upgrade to v2 | Mount API changes |
| vue-apollo | 3.x | ❌ No | Migrate to @vue/apollo-composable v4 | Composition API |
| vue-analytics | Any | ❌ No | Replace with vue-gtag v2 | Different API |
| vue-notification | Any | ❌ No | Replace with @kyvg/vue3-notification | Different package |
| vue-js-modal | 1.x/2.x | ❌ No | Replace with vue-final-modal v4 | Complete replacement |
| vue-toasted | Any | ❌ No | Replace with vue-toastification | Complete replacement |
| vue-lazyload | 1.x | ⚠️ Partial | Upgrade to v3 or replace | API changes |
| vuedraggable | 2.x | ❌ No | Upgrade to v4+ | Vue 3 version |
| vue-chartjs | 3.x | ❌ No | Upgrade to v5 | Chart.js 4 + Vue 3 |
| vue-good-table | 2.x | ❌ No | Replace with vue-good-table-next | Community fork |
| vue-select | 3.x | ⚠️ Partial | Upgrade to v4 | Vue 3 compatible |
| v-calendar | 2.x | ❌ No | Upgrade to v3 | Vue 3 version |
| nuxt | 2.x | ❌ No | Migrate to Nuxt 3 | **Complete rewrite** |
| @nuxtjs/* modules | 2.x | ❌ No | Find Nuxt 3 equivalents | Most have v3 versions |

### 4. Architecture Evaluation

Assess:
- **Vuex Modularity**: Store structure, namespacing
- **Component Coupling**: Mixins, provide/inject usage
- **Global State**: Non-store global state patterns
- **Build Tooling**: Migration path complexity
- **Type Safety**: TypeScript adoption level
- **UI Library Integration**:
  - Depth of integration (shallow/moderate/deep)
  - Custom theming complexity
  - Global vs local component registration
  - Direct DOM manipulation patterns
  - Style override patterns (SCSS/CSS variables)
  - Plugin architecture dependencies
- **TypeScript & Build Tooling**:
  - TypeScript version and strict mode usage
  - Transpiler choice and configuration complexity
  - Type coverage (% of typed vs untyped files)
  - Decorator usage patterns (experimentalDecorators)
  - Build performance and optimization level
  - Development server and HMR capabilities
  - Bundle size and tree-shaking effectiveness

## Output Document

You MUST produce a **Migration Analysis & Trade-offs Document** with these sections:

### Required Document Structure

```markdown
# Vue 2 → Vue 3 Migration Analysis

## 1. Executive Summary
[2-3 paragraph overview of findings and recommendation]

## 2. Current Project State

### Project Overview
- Vue Version: [version]
- Build System: [tool]
- TypeScript: [Yes/No/Partial]
- Test Coverage: [status]

### Architecture Summary
[Description of current architecture]

### Project Variant
- Type: [Standard Vue 2 / Vue 2.7 / Nuxt 2 / Vue 2 + SSR / Monorepo]
- Impact: [Standard migration / Reduced scope / Different migration path]

### Key Metrics
- Total Components: [count]
- Vuex Modules: [count]
- Mixins: [count]
- Custom Filters: [count]
- Third-party Dependencies: [count]
- Class Components (vue-class-component): [count]
- Components with vue-property-decorator: [count]
- Components with vuex-class: [count]
- Render Function Components: [count]
- JSX Components: [count]
- Functional Components: [count]
- Custom Directives: [count]
- Global API Usages (Vue.use, Vue.component, etc.): [count]
- Vue.prototype Additions: [count]
- Event Bus Usages ($on/$off/$once): [count]
- .sync Modifier Usages: [count]
- $listeners Usages: [count]
- $scopedSlots Usages: [count]
- $children Usages: [count]
- Vue.set/Vue.delete Usages: [count]
- ::v-deep Usages: [count]
- require() / require.context() Usages: [count]
- process.env.VUE_APP_* Usages: [count]
- Third-Party Ecosystem Packages Needing Migration: [count]

### UI Component Library
- Library: [name and version]
- Vue 3 Compatible: [Yes/No/Partial]
- Components Used: [count]
- Migration Path: [Available/Requires Replacement/Requires Rewrite]
- Impact Level: [Low/Medium/High/Very High]

### TypeScript & Build Configuration
- TypeScript Version: [version]
- Vue 3 Compatible: [Yes/No - requires upgrade to 4.5+]
- Transpiler: [Babel/tsc/SWC/esbuild/other]
- Build Tool: [Vue CLI/Vite/Webpack/Rollup]
- Strict Mode: [Enabled/Disabled]
- Decorator Usage: [Yes/No/Count]
- Type Coverage: [percentage or description]
- Migration Complexity: [Low/Medium/High/Very High]

## 3. Migration Strategy

### Recommended Approach
[Incremental / Big-bang / Hybrid]

### Migration Phases
1. [Phase 1 description]
2. [Phase 2 description]
3. [Phase 3 description]

## 4. Proposed Technical Changes

### Core Framework
- [ ] Vue 2 → Vue 3
- [ ] Vue Router 3 → Vue Router 4
- [ ] Vuex → Pinia

### Component Migration
- [ ] Options API → Composition API
- [ ] Class Components → Composition API (`<script setup>`)
- [ ] vue-property-decorator → Vue 3 macros (defineProps, defineEmits, etc.)
- [ ] vuex-class → Pinia composables
- [ ] Mixins → Composables
- [ ] Filters → Methods/Computed

### Build System
- [ ] [Current Build Tool] → [Target Build Tool]
- [ ] Update build configurations
- [ ] Migrate environment variables
- [ ] Update CI/CD pipelines

### TypeScript & Transpilation
- [ ] TypeScript [current version] → [4.5+ or 5.x]
- [ ] Update tsconfig.json for Vue 3 compatibility
- [ ] Migrate/update transpiler configuration
- [ ] Update type declaration files (*.d.ts)
- [ ] Remove Vue 2 shims (shims-vue.d.ts)
- [ ] Add vue-tsc for type checking
- [ ] Update Babel plugins (if using Babel)
- [ ] Configure JSX/TSX handling for Vue 3
- [ ] Update build scripts in package.json

### UI Component Library Migration
- [ ] [Current Library] → [Target Library/Version]
- [ ] Theme/Styling Migration
- [ ] Component API Updates
- [ ] Breaking Changes Resolution
- [ ] Icon Library Updates (if applicable)

## 5. UI Component Library Strategy

### Current Library Analysis
- **Library**: [name and version]
- **Usage**: [number of components, usage patterns]
- **Custom Configuration**: [theme, plugins, etc.]

### Migration Options

#### Option 1: [Upgrade to Vue 3 Compatible Version]
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- [Maintain familiar API]
- [Official migration guide available]
**Cons**:
- [Breaking changes to address]
- [Theme reconfiguration needed]

#### Option 2: [Migrate to Alternative Library]
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- [Better Vue 3 support]
- [Modern features]
**Cons**:
- [Learning curve]
- [Component rewrites needed]

#### Option 3: [Build Custom Components]
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- [Full control]
- [No third-party dependencies]
**Cons**:
- [High maintenance]
- [Significant development effort]

### Recommendation
[Which option and detailed rationale]

### Migration Checklist
- [ ] Audit all library component usage
- [ ] Identify deprecated features
- [ ] Plan theme/styling migration
- [ ] Update component imports
- [ ] Refactor component props/events
- [ ] Update global configurations
- [ ] Test visual regression
- [ ] Update documentation

## 5.1 TypeScript & Build Tool Strategy

### Current Configuration Analysis
- **TypeScript Version**: [version]
- **Transpiler**: [Babel/tsc/SWC/esbuild]
- **Build Tool**: [Vue CLI/Webpack/Vite/other]
- **Configuration Complexity**: [simple/moderate/complex]
- **Custom Plugins**: [list any custom webpack/babel plugins]

### Migration Options

#### Option 1: Minimal Upgrade (Keep Current Stack)
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- Minimal changes to existing workflow
- Team familiarity with current tools
- Lower risk of build issues
**Cons**:
- May miss performance improvements
- Potential compatibility issues with old tools
- Missing modern features

**Required Changes**:
- [ ] Upgrade TypeScript to 4.5+ minimum
- [ ] Update tsconfig.json for Vue 3
- [ ] Update transpiler plugins/presets
- [ ] Add vue-tsc for type checking
- [ ] Update type declarations

#### Option 2: Modernize Build Stack (Migrate to Vite)
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- Official Vue 3 recommendation
- Significantly faster development server (HMR)
- Simpler configuration
- Better developer experience
- Built-in TypeScript support with esbuild
**Cons**:
- Learning curve for team
- Need to migrate build configurations
- Different plugin ecosystem
- May require CI/CD updates

**Required Changes**:
- [ ] Install Vite and @vitejs/plugin-vue
- [ ] Create vite.config.ts
- [ ] Migrate environment variables (.env files)
- [ ] Update import paths (remove webpack aliases)
- [ ] Migrate custom webpack loaders to Vite plugins
- [ ] Update build scripts in package.json
- [ ] Update TypeScript to 5.x recommended
- [ ] Configure Vitest (if replacing Jest)

#### Option 3: Hybrid Approach (Upgrade TS + Keep Build Tool)
**Feasibility**: [High/Medium/Low]
**Effort**: [Low/Medium/High]
**Pros**:
- Incremental migration reduces risk
- Upgrade TypeScript first, build tool later
- Can validate Vue 3 compatibility before major build changes
**Cons**:
- Multi-phase migration
- Longer migration timeline
- May need to revisit build config later

**Required Changes**:
- Phase 1: Upgrade TypeScript and transpiler
- Phase 2: Migrate to Vite/modern build tool (optional)

### Recommendation
[Which option and detailed rationale considering project size, team expertise, and timeline]

### TypeScript Migration Checklist
- [ ] Upgrade TypeScript to 4.5+ (5.x recommended)
- [ ] Update tsconfig.json compiler options
- [ ] Add "moduleResolution": "bundler" (for Vite)
- [ ] Update JSX configuration
- [ ] Remove Vue 2 type shims (shims-vue.d.ts)
- [ ] Add vue-tsc to devDependencies
- [ ] Update type imports from vue
- [ ] Fix any new TypeScript errors from stricter types
- [ ] Update CI/CD type checking scripts
- [ ] Configure IDE/editor for Vue 3 types

### Build Tool Migration Checklist (if migrating to Vite)
- [ ] Install Vite and Vue 3 plugin
- [ ] Create vite.config.ts
- [ ] Migrate environment variables (VITE_ prefix)
- [ ] Update index.html structure (move to root)
- [ ] Migrate webpack aliases to Vite aliases
- [ ] Replace webpack-specific imports
- [ ] Update asset handling (import.meta.url)
- [ ] Migrate custom webpack plugins to Vite
- [ ] Update test configuration (Vitest)
- [ ] Update build scripts and CI/CD

## 6. Trade-offs & Alternatives

### Option A: [Approach Name]
**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

### Option B: [Approach Name]
[Similar structure]

### Recommendation
[Which option and why]

## 7. Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
| UI Library incompatibility | [level] | [level] | [Strategy for migration/replacement] |
| Theme/styling regression | [level] | [level] | [Visual testing strategy] |
| TypeScript compilation errors | [level] | [level] | [Incremental strict mode, type fixes] |
| Build tool migration issues | [level] | [level] | [Parallel build setup, thorough testing] |
| Performance regression | [level] | [level] | [Benchmark before/after, optimize bundle] |

## 8. Estimated Effort & Complexity

### Complexity Assessment
- Overall Complexity: [Low/Medium/High/Very High]
- Breaking Changes: [count]
- Major Refactors: [count]

### Effort Breakdown
| Area | Complexity | Notes |
|------|------------|-------|
| State Management | [level] | [notes] |
| Components | [level] | [notes] |
| Routing | [level] | [notes] |
| TypeScript & Transpilation | [level] | [notes] |
| Build System Migration | [level] | [notes] |
| UI Library Migration | [level] | [notes] |

## 9. Open Questions / Assumptions

### Assumptions Made
1. [Assumption 1]
2. [Assumption 2]

### Questions for Stakeholder
1. [Question 1]
2. [Question 2]

## 10. Go / No-Go Recommendation

### Recommendation: [GO / NO-GO / CONDITIONAL GO]

### Rationale
[Explanation of recommendation]

### Prerequisites (if conditional)
1. [Prerequisite 1]
2. [Prerequisite 2]
```

## Analysis Checklists

### Vue 2 → Vue 3 Breaking Changes to Check

- [ ] `$on`, `$off`, `$once` removed (Event Bus pattern)
- [ ] Filters removed (use methods/computed)
- [ ] `Vue.set` / `Vue.delete` removed
- [ ] `.native` modifier removed
- [ ] `$children` removed
- [ ] `$listeners` removed (merged into `$attrs`)
- [ ] `$scopedSlots` removed (unified slots)
- [ ] Functional components syntax changed
- [ ] Async components syntax changed
- [ ] Custom directives API changed
- [ ] Transition class names changed
- [ ] v-model changes (prop/event names)
- [ ] v-if/v-for precedence changed
- [ ] Array watching behavior changed
- [ ] Props default factory `this` access removed
- [ ] `.sync` modifier removed (use `v-model:propName`)
- [ ] `v-model` default prop/event changed (`value`/`input` → `modelValue`/`update:modelValue`)
- [ ] Multiple `v-model` bindings on single component (new feature)
- [ ] `v-if` / `v-for` precedence changed (v-if now higher priority)
- [ ] `key` usage on `<template v-for>` (now placed on `<template>`)
- [ ] `Vue.set()` / `Vue.delete()` / `this.$set()` / `this.$delete()` removed
- [ ] `Vue.observable()` removed (use `reactive()`)
- [ ] `Vue.extend()` remove

…(truncated)