GUÍA COMPLETA PARA MIGRAR DE VUE 2 A VUE 3

November 28, 2025

Introducción a la Migración de Vue 2 a Vue 3

Vue.js es un framework de JavaScript ampliamente utilizado para construir interfaces de usuario dinámicas y reactivas. Desde su lanzamiento en 2014, ha evolucionado significativamente, y en septiembre de 2020 se introdujo Vue 3, una versión que trajo mejoras en rendimiento, nuevas APIs y una arquitectura más flexible. Migrar de Vue 2 a Vue 3 es una tarea esencial para desarrolladores que desean aprovechar estas mejoras, especialmente en 2025, cuando Vue 2 ha alcanzado el fin de su soporte oficial. Este tutorial proporciona una guía paso a paso para realizar esta migración, utilizando un proyecto de ejemplo para ilustrar los cambios clave, desde la configuración inicial hasta la optimización de componentes.

La migración no solo permite adoptar las mejoras de rendimiento de Vue 3, sino que también prepara las aplicaciones para el futuro, integrando herramientas modernas como Vite y la API de Composición. A continuación, exploraremos los pasos necesarios, los cambios en las APIs, las herramientas recomendadas y las mejores prácticas para garantizar una transición fluida.

Preparación del Proyecto para la Migración

Antes de comenzar, es fundamental preparar el entorno de desarrollo. La migración de Vue 2 a Vue 3 requiere una evaluación cuidadosa del proyecto existente para identificar dependencias, configuraciones y posibles puntos de ruptura. El primer paso es asegurarse de que el proyecto esté utilizando la última versión de Vue 2 (2.7.x), ya que esta versión incluye características de compatibilidad que facilitan la transición.

Crea un respaldo completo del proyecto, idealmente utilizando un sistema de control de versiones como Git. Esto permite revertir cambios en caso de problemas. A continuación, revisa el archivo package.json para identificar las dependencias relacionadas con Vue. Por ejemplo, un proyecto típico de Vue 2 podría tener una configuración similar a la siguiente:

{
  "dependencies": {
    "vue": "^2.6.14",
    "vue-router": "^3.5.3",
    "vuex": "^3.6.2"
  },
  "devDependencies": {
    "@vue/cli-service": "^4.5.13",
    "vue-template-compiler": "^2.6.14"
  }
}

Actualiza estas dependencias a las versiones compatibles con Vue 3. Por ejemplo, vue-template-compiler debe reemplazarse por @vue/compiler-sfc, y las versiones de vue-router y vuex deben actualizarse a las compatibles con Vue 3 (o considerar Pinia como alternativa a Vuex). Ejecuta el siguiente comando para instalar la última versión de Vue CLI si usas esta herramienta:

npm install -g @vue/cli@latest

Configuración del Entorno con Vite

Vue 3 fomenta el uso de Vite como herramienta de construcción, en lugar de Webpack o Vue CLI, debido a su rapidez y simplicidad. Vite ofrece un entorno de desarrollo más eficiente gracias a su compilación bajo demanda. Para configurar un proyecto con Vite, crea una nueva estructura de proyecto e integra los archivos de Vue 2 progresivamente.

Ejecuta el siguiente comando para inicializar un proyecto de Vue 3 con Vite:

npm create vite@latest mi-proyecto-vue3 -- --template vue

Esto genera una estructura de directorios básica:

mi-proyecto-vue3/
├── node_modules/
├── public/
│   ├── favicon.ico
├── src/
│   ├── assets/
│   ├── components/
│   │   ├── HelloWorld.vue
│   ├── App.vue
│   ├── main.js
├── index.html
├── package.json
├── vite.config.js

Una vez configurado, instala las dependencias necesarias:

cd mi-proyecto-vue3
npm install

Para integrar un proyecto existente, copia los componentes, plantillas y lógica de negocio desde el proyecto de Vue 2 al directorio src. Por ejemplo, si tienes un componente TodoList.vue, muévelo a src/components/ y revisa su sintaxis para ajustarla a Vue 3.

Actualización de Dependencias Clave

La migración requiere actualizar las dependencias principales. A continuación, se detalla cómo manejar las más comunes:

Vue: Reemplaza vue por la versión 3.x. Instala también @vue/compat para usar el modo de compatibilidad, que permite ejecutar código de Vue 2 en Vue 3 mientras se realizan ajustes.

npm install vue@^3.4.0 @vue/compat@^3.4.0

Vue Router: La versión 4.x es compatible con Vue 3. Actualiza con:

npm install vue-router@^4.2.5

Vuex o Pinia: Vuex 4 es compatible con Vue 3, pero Pinia es la opción recomendada para la gestión de estado en 2025 debido a su simplicidad y soporte para la API de Composición.

npm install pinia@^2.1.7

Configura Pinia en main.js:

import { createApp } from "vue";
import { createPinia } from "pinia";
import App from "./App.vue";

const app = createApp(App);
app.use(createPinia());
app.mount("#app");

Revisa otras dependencias, como bibliotecas de UI (por ejemplo, Vuetify o Element Plus), y asegúrate de que sean compatibles con Vue 3. Si una biblioteca no tiene soporte, busca alternativas o refactoriza los componentes afectados.

Uso del Modo de Compatibilidad

El modo de compatibilidad, proporcionado por @vue/compat, permite ejecutar aplicaciones de Vue 2 en Vue 3 con advertencias sobre características obsoletas. Para habilitarlo, modifica el archivo main.js:

import { createApp } from "vue";
import { createVueCompat } from "@vue/compat";
import App from "./App.vue";

const app = createApp(App, createVueCompat());
app.mount("#app");

Este modo es útil para proyectos grandes, ya que permite migrar componentes gradualmente. Sin embargo, ten en cuenta que algunas APIs obsoletas, como los filtros, no son compatibles incluso en este modo. Por ejemplo, un filtro en Vue 2 como el siguiente:

<template>
    <p>{{ text | capitalize }}</p>
</template>

<script>
export default {
    data() {
        return { text: "hola" };
    },
    filters: {
        capitalize(value) {
            return value.charAt(0).toUpperCase() + value.slice(1);
        },
    },
};
</script>

Debe reemplazarse por un método o una función en Vue 3:

<template>
    <p>{{ capitalize(text) }}</p>
</template>

<script>
export default {
    data() {
        return { text: "hola" };
    },
    methods: {
        capitalize(value) {
            return value.charAt(0).toUpperCase() + value.slice(1);
        },
    },
};
</script>

Cambios en la API Global

Vue 3 introduce cambios significativos en la API global de Vue, que afecta cómo se crean las aplicaciones y se configuran los complementos. En Vue 2, la instancia de Vue se creaba así:

import Vue from "vue";
import App from "./App.vue";
import router from "./router";

Vue.use(router);
new Vue({
    router,
    render: (h) => h(App),
}).$mount("#app");

En Vue 3, se utiliza createApp para una inicialización más modular:

import { createApp } from "vue";
import App from "./App.vue";
import router from "./router";

const app = createApp(App);
app.use(router);
app.mount("#app");

Este cambio mejora la encapsulación y permite múltiples instancias de Vue en la misma página. Asegúrate de actualizar todos los complementos para que usen app.use() en lugar de Vue.use().

Adopción de la API de Composición

La API de Composición es una de las mayores innovaciones de Vue 3, diseñada para mejorar la reutilización y organización del código. Aunque la API de Opciones sigue siendo compatible, la API de Composición es ideal para proyectos nuevos o al refactorizar componentes complejos.

Considera un componente de Vue 2 que usa la API de Opciones:

<template>
    <div>
        <p>Contador: {{ count }}</p>
        <button @click="increment">Incrementar</button>
    </div>
</template>

<script>
export default {
    data() {
        return {
            count: 0,
        };
    },
    methods: {
        increment() {
            this.count++;
        },
    },
};
</script>

El equivalente con la API de Composición es:

<template>
    <div>
        <p>Contador: {{ count }}</p>
        <button @click="increment">Incrementar</button>
    </div>
</template>

<script>
import { ref } from "vue";

export default {
    setup() {
        const count = ref(0);
        const increment = () => {
            count.value++;
        };
        return { count, increment };
    },
};
</script>

La función setup centraliza la lógica del componente, y ref crea variables reactivas. Este enfoque es más flexible para componentes con lógica compleja y facilita la creación de composables, funciones reutilizables que encapsulan lógica.

Ajustes en Componentes y Directivas

Vue 3 introduce cambios en la forma en que se declaran y utilizan los componentes. Por ejemplo, la opción data siempre debe ser una función en Vue 3, incluso en componentes raíz. Además, las directivas como v-if y v-for tienen un nuevo orden de precedencia cuando se usan juntas. En Vue 2, v-for tenía prioridad, pero en Vue 3, v-if tiene precedencia, lo que puede afectar el renderizado.

Por ejemplo, en Vue 2:

<div v-if="condition" v-for="item in items">
  {{ item }}
</div>

Podría generar un comportamiento inesperado en Vue 3. Refactoriza para evitar ambigüedades:

<template v-for="item in items">
    <div v-if="condition">
        {{ item }}
    </div>
</template>

Además, las transiciones en Vue 3 han cambiado. La directiva v-on="$listeners" se reemplaza por v-bind="$attrs" para eventos personalizados. Por ejemplo:

<template>
    <input
        v-bind="$attrs"
        @input="$emit('update:modelValue', $event.target.value)"
    />
</template>

<script>
export default {
    inheritAttrs: false,
};
</script>

Migración de Vue Router

Vue Router 4 introduce cambios en la sintaxis y la configuración. Por ejemplo, la creación del enrutador ahora usa createRouter y requiere especificar el modo de historial:

import { createRouter, createWebHistory } from "vue-router";
import Home from "../views/Home.vue";

const routes = [
    {
        path: "/",
        name: "Home",
        component: Home,
    },
];

const router = createRouter({
    history: createWebHistory(),
    routes,
});

export default router;

Asegúrate de actualizar las rutas y los componentes de navegación, como <router-link> y <router-view>, para que sean compatibles con Vue Router 4.

Gestión de Estado con Pinia

Pinia es la opción recomendada para la gestión de estado en Vue 3. A diferencia de Vuex, Pinia es más ligero y está diseñado para integrarse con la API de Composición. Define un almacén de estado en stores/counter.js:

import { defineStore } from "pinia";

export const useCounterStore = defineStore("counter", {
    state: () => ({
        count: 0,
    }),
    actions: {
        increment() {
            this.count++;
        },
    },
});

Usa el almacén en un componente:

<template>
    <div>
        <p>Contador: {{ counter.count }}</p>
        <button @click="counter.increment">Incrementar</button>
    </div>
</template>

<script>
import { useCounterStore } from "../stores/counter";

export default {
    setup() {
        const counter = useCounterStore();
        return { counter };
    },
};
</script>

Pinia elimina la necesidad de mutaciones y simplifica la gestión de estado, lo que lo hace ideal para proyectos modernos.

Pruebas y Depuración

Durante la migración, realiza pruebas exhaustivas para identificar errores. Usa herramientas como Vitest para pruebas unitarias y Playwright para pruebas de extremo a extremo. Configura Vitest en el proyecto:

npm install vitest @vitejs/plugin-vue --save-dev

Actualiza vite.config.js:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
    plugins: [vue()],
    test: {
        environment: "jsdom",
    },
});

Escribe una prueba para un componente:

import { mount } from "@vue/test-utils";
import Counter from "./Counter.vue";

test("incrementa el contador al hacer clic", async () => {
    const wrapper = mount(Counter);
    await wrapper.find("button").trigger("click");
    expect(wrapper.text()).toContain("Contador: 1");
});

Ejecuta las pruebas con:

npx vitest

Las advertencias en la consola durante el desarrollo también son útiles para identificar usos obsoletos de APIs.

Ejemplo Práctico: Aplicación de Lista de Tareas

Para ilustrar la migración, consideremos una aplicación de lista de tareas en Vue 2. La estructura original podría ser:

todo-app/
├── src/
│   ├── components/
│   │   ├── TodoItem.vue
│   │   ├── TodoList.vue
│   ├── App.vue
│   ├── main.js
├── package.json

El componente TodoList.vue en Vue 2:

<template>
    <div>
        <input v-model="newTodo" @keyup.enter="addTodo" />
        <ul>
            <todo-item v-for="todo in todos" :key="todo.id" :todo="todo" />
        </ul>
    </div>
</template>

<script>
import TodoItem from "./TodoItem.vue";

export default {
    components: { TodoItem },
    data() {
        return {
            newTodo: "",
            todos: [],
        };
    },
    methods: {
        addTodo() {
            if (this.newTodo.trim()) {
                this.todos.push({
                    id: Date.now(),
                    text: this.newTodo,
                    done: false,
                });
                this.newTodo = "";
            }
        },
    },
};
</script>

Migra este componente a Vue 3 usando la API de Composición:

<template>
    <div>
        <input v-model="newTodo" @keyup.enter="addTodo" />
        <ul>
            <todo-item v-for="todo in todos" :key="todo.id" :todo="todo" />
        </ul>
    </div>
</template>

<script>
import { ref } from "vue";
import TodoItem from "./TodoItem.vue";

export default {
    components: { TodoItem },
    setup() {
        const newTodo = ref("");
        const todos = ref([]);

        const addTodo = () => {
            if (newTodo.value.trim()) {
                todos.value.push({
                    id: Date.now(),
                    text: newTodo.value,
                    done: false,
                });
                newTodo.value = "";
            }
        };

        return { newTodo, todos, addTodo };
    },
};
</script>

Actualiza main.js para usar Vite y Pinia:

import { createApp } from "vue";
import { createPinia } from "pinia";
import App from "./App.vue";

const app = createApp(App);
app.use(createPinia());
app.mount("#app");

Este ejemplo demuestra cómo refactorizar componentes, adoptar nuevas APIs y configurar un entorno moderno.

Mejores Prácticas para la Migración

Para garantizar una migración exitosa, sigue estas recomendaciones:

Realiza la migración en un entorno de pruebas y usa ramas de Git para experimentar.
Prioriza la refactorización de componentes críticos antes de adoptar la API de Composición en todo el proyecto.
Aprovecha la comunidad de Vue, incluyendo la documentación oficial y foros, para resolver problemas específicos.
Monitorea el rendimiento de la aplicación después de la migración, utilizando herramientas como Lighthouse.
Documenta los cambios realizados para facilitar el mantenimiento futuro.

Conclusiones

Migrar de Vue 2 a Vue 3 es un paso estratégico para modernizar aplicaciones web en 2025. Aunque la transición puede presentar desafíos, como la actualización de dependencias y la refactorización de componentes, las mejoras en rendimiento, la flexibilidad de la API de Composición y el soporte para herramientas como Vite y Pinia hacen que valga la pena. Este tutorial ha cubierto los pasos esenciales, desde la preparación del proyecto hasta la implementación de un ejemplo práctico, proporcionando una base sólida para abordar la migración. Al seguir las mejores prácticas y realizar pruebas exhaustivas, los desarrolladores pueden garantizar que sus aplicaciones no solo sean compatibles con Vue 3, sino que también estén preparadas para las demandas del desarrollo web moderno.