If you're reading this, you've probably heard the horror stories: "Vuetify 2 to 3 migration is a nightmare." "They might as well be two completely different libraries." "Every component breaks." We've heard them all—and we've lived them. After migrating dozens of Vue 2 + Vuetify 2 applications to Vue 3 + Vuetify 3, we've built a comprehensive playbook that turns this nightmare into a manageable, predictable process. This is that playbook.
Why the Vuetify Migration Is So Painful
Let's start by acknowledging the truth: the Vuetify 2-to-3 migration is genuinely difficult. It's not just marketing hyperbole. Here's why:
1. Fundamental Architecture Changes
Vuetify 3 isn't just an update—it's a complete rewrite. The layout system was overhauled. The theming system changed. Component APIs were redesigned from the ground up. This isn't a "find and replace" migration; it's a systematic refactor.
2. The @vue/compat Trap
Vue 3's compatibility build (@vue/compat) was designed to allow incremental migration. But here's the catch: it doesn't work well with Vuetify 3. This breaks the primary incremental migration path, forcing a "big-bang" rewrite that most teams can't risk.
3. Missing and Changed Components
Critical components like v-data-table and v-calendar were missing from Vuetify 3 for a long time. Even when they arrived, their APIs were completely different. Every usage needs to be refactored.
4. Prop and Event Renames
Countless props were renamed. value became modelValue. Events changed. Slots were restructured. There's no comprehensive migration guide that covers everything—you learn by breaking things.
Our Migration Playbook
After dozens of migrations, we've systematized the process. Here's our step-by-step playbook:
Pre-Migration Audit
Before touching a single line of code, we conduct a comprehensive audit:
- Catalog every Vuetify component used in your codebase
- Identify deprecated components and their Vuetify 3 replacements
- Map all prop renames and API changes
- Document custom component dependencies
- Create a component-by-component migration checklist
Infrastructure Setup
Before migrating components, we set up the new infrastructure:
// Install Vue 3 + Vuetify 3
npm install vue@^3.4.0 vuetify@^3.5.0
// Update Vite config for Vuetify 3
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vuetify from 'vite-plugin-vuetify'
export default defineConfig({
plugins: [
vue(),
vuetify({ autoImport: true })
]
})- Upgrade to Vue 3 and Vuetify 3 in a separate branch
- Configure Vuetify 3 theme system (completely different from v2)
- Set up Vite (Vuetify 3 requires it—no more Webpack)
- Create wrapper components for missing/changed components
Component Migration Strategy
We migrate components in a specific order to minimize breaking changes:
Tier 1: Simple Components (Low Risk)
Buttons, cards, chips, icons. These typically need minimal changes—mostly prop renames.
Tier 2: Form Components (Medium Risk)
Text fields, selects, checkboxes, radio buttons. These require careful attention to v-model changes and event handling.
Tier 3: Complex Components (High Risk)
Data tables, calendars, date pickers, complex forms. These often require complete rewrites.
Common Pitfalls We've Learned to Avoid
❌ Pitfall #1: Assuming @vue/compat Will Help
Don't rely on @vue/compat for Vuetify components. It doesn't work. You need to migrate Vue and Vuetify together, or not at all.
❌ Pitfall #2: Migrating Components in Random Order
Start with leaf components (components that don't depend on others) and work your way up. Migrating a parent component before its children will break everything.
❌ Pitfall #3: Not Testing After Each Component
Test immediately after migrating each component. If you wait until the end, you'll have hundreds of errors with no idea where they came from.
❌ Pitfall #4: Ignoring Layout System Changes
Vuetify 3's grid system is completely different. All your v-row and v-col components need to be updated. This is often the most time-consuming part.
Component-Specific Changes (The Cheat Sheet)
Here are the most common component changes we encounter:
v-data-table → v-data-table-server / v-data-table
The data table API changed completely. Server-side tables now use v-data-table-server. Client-side tables have a new slot structure.
// Vuetify 2
<v-data-table :items="items" :headers="headers">
<template v-slot:item.action="{ item }">
<v-btn @click="handleAction(item)">Action</v-btn>
</template>
</v-data-table>
// Vuetify 3
<v-data-table :items="items" :headers="headers">
<template #item.action="{ item }">
<v-btn @click="handleAction(item)">Action</v-btn>
</template>
</v-data-table>v-model → modelValue
All components that used value prop now use modelValue. Events changed from @input to @update:modelValue.
Grid System Overhaul
The entire grid system changed. v-container, v-row, and v-col all have new prop structures. Spacing, breakpoints, and alignment work differently.
Our Pre-Built Solutions
Over time, we've built a library of wrapper components and migration utilities that speed up the process:
- Component Wrappers: Pre-built wrappers for components that don't have direct Vuetify 3 equivalents
- Migration Scripts: Automated scripts that handle common find-and-replace operations
- Testing Utilities: Custom test helpers that work with Vuetify 3's new component structure
- Theme Migration Tools: Automated conversion of Vuetify 2 theme configs to Vuetify 3 format
Why Specialization Matters
Generalist agencies will attempt this migration and learn on your dime. They'll hit every pitfall, go over budget, and prove the "nightmare" reputation correct. We've already made every mistake possible—so you don't have to.
What Makes Us Different
- We've done this dozens of times. We know every component that will break and exactly how to fix it.
- We have pre-built solutions. Wrapper components, migration scripts, and testing utilities that speed up the process.
- We give fixed-price quotes. Our audits allow us to scope the project accurately, so you know exactly what it will cost.
- We don't learn on your dime. We've already made every mistake. You get the benefit of our experience.
Don't Let Your Team Learn This the Hard Way
The Vuetify migration is a nightmare—but it doesn't have to be your nightmare. Get a comprehensive audit that identifies every component that will break and exactly how we'll fix it. Then get a fixed-price quote for the full migration.
✓ Component-by-component migration plan ✓ Fixed-price guarantee ✓ Vuetify 3 expertise
Conclusion
The Vuetify 2-to-3 migration is difficult, but it's not impossible. With the right playbook, the right tools, and the right team, it becomes a manageable, predictable process. The key is specialization: don't let a generalist agency learn on your dime. Hire a team that's already made every mistake and built every solution.
We've documented every pitfall, built every wrapper, and systematized every step. This playbook is the result of dozens of successful migrations. Use it, or hire us to execute it for you.