Guías

Vue 3 incluye las dos API. La Options API es la que Vue ha tenido siempre: un componente es un objeto con `data`, `computed`, `methods`, `watch` y los hooks de ciclo de vida como propiedades con nombre. La Composition API, introducida en Vue 3, permite escribir la misma lógica como funciones normales dentro de una función `setup()` o de un bloque `<script setup>`. Ninguna está obsoleta y ninguna va a desaparecer.

La Options API organiza el código por tipo de opción. Todo el estado reactivo va en `data()`. Todos los valores calculados van en `computed`. Todos los métodos van en `methods`. Es claro en componentes pequeños, porque cada asunto ocupa unas pocas líneas en cada sección y las secciones se recorren rápido. Se convierte en un problema cuando el componente crece, porque una sola funcionalidad (por ejemplo, un filtro de búsqueda) tiene su estado en `data`, sus valores derivados en `computed`, sus manejadores de eventos en `methods` y su inicialización en `mounted`. La funcionalidad queda repartida en cuatro lugares del archivo.

Cómo organiza el código la Options API

La Composition API organiza el código por responsabilidad lógica. En lugar de poner todo el estado en un sitio y todos los métodos en otro, se agrupan el estado, los valores calculados, los watchers y las funciones que pertenecen a una misma funcionalidad. Un filtro de búsqueda se convierte en un bloque de 15 líneas que contiene todo lo que necesita. La paginación se convierte en otro bloque. Están uno junto a otro en el archivo, y se puede leer uno sin saltar a otras tres secciones.

Esto solo importa en componentes grandes. Un componente con un estado, un valor calculado y un método se lee igual de bien con cualquiera de las dos API. La Composition API empieza a compensar cuando un componente tiene tres o más responsabilidades independientes, porque es entonces cuando la Options API obliga a intercalar lógica sin relación entre las secciones.

Cómo organiza el código la Composition API

`<script setup>` es la sintaxis que usa la mayor parte del código nuevo de Vue 3. Es un atajo de compilación que evita escribir una función `setup()` explícita y su instrucción de retorno. Las variables declaradas en el nivel superior están disponibles directamente en el template. Las props se declaran con `defineProps()` y los eventos con `defineEmits()`. Ambas son macros del compilador que no hace falta importar.

• La Options API organiza el código por tipo (data, computed, methods); la Composition API lo organiza por funcionalidad
• Ninguna de las dos API está obsoleta, y ambas usan el mismo sistema de reactividad
• ref() es la opción por defecto recomendada frente a reactive(), para evitar errores de reasignación y desestructuración
• Los composables sustituyen a los mixins para reutilizar lógica entre componentes sin colisiones de nombres
• La inferencia de TypeScript funciona de forma natural con la Composition API y tiene dificultades con el this de la Options API
• La migración es opcional: las dos API conviven en el mismo proyecto e incluso en el mismo componente

La reactividad en la Composition API usa `ref()` y `reactive()`. `ref()` envuelve un único valor y exige `.value` para leerlo o escribirlo en JavaScript (pero no en el template, donde Vue lo desenvuelve automáticamente). `reactive()` envuelve un objeto cuyas propiedades son reactivas sin `.value`. La fuente de errores más común es olvidar `.value` en el script, o usarlo en el template, donde no hace falta.

ref, reactive y script setup

`ref()` es casi siempre la opción por defecto correcta. `reactive()` tiene dos restricciones que pillan a mucha gente. Primero, no se puede reasignar el objeto entero (el proxy está sobre la referencia original, no sobre la variable). Segundo, desestructurar un objeto reactivo hace perder la reactividad a las propiedades extraídas. `ref()` no tiene ninguno de los dos problemas, y el coste de `.value` es pequeño comparado con lo que cuesta depurar esos casos límite.

Los composables son la principal ventaja estructural. Un composable es una función que usa las primitivas de la Composition API (`ref`, `computed`, `watch`, `onMounted`) y devuelve estado reactivo. `useMouse()`, `useFetch()` y `useLocalStorage()` son ejemplos típicos. Se llaman en `setup()` y devuelven valores reactivos. Es el patrón que la Options API no puede reproducir limpiamente: los mixins comparten lógica entre componentes, pero fusionan las propiedades por nombre, lo que crea colisiones silenciosas e impide saber de dónde viene una propiedad.

Los mixins son el equivalente en la Options API, y dan problemas a gran escala. Si dos mixins definen una propiedad `data` con el mismo nombre, una gana sin avisar. Si un mixin añade un método, el componente no tiene ninguna declaración visible de él. El origen de una propiedad se vuelve ambiguo a medida que se añaden mixins. La documentación de Vue recomienda explícitamente los composables en lugar de los mixins para reutilizar lógica en Vue 3.

Composables frente a mixins

El soporte de TypeScript es claramente mejor en la Composition API. La Options API necesita el envoltorio `defineComponent()`, y la inferencia de tipos pasa por un tipo `this` complejo que tiene dificultades con ciertos patrones (callbacks anidados, funciones externas que leen el estado del componente). La Composition API usa variables normales con tipos estándar de TypeScript. `ref<number>(0)` da un `Ref<number>`. Los composables tienen valores de retorno tipados. La ayuda del IDE (autocompletado, tipos al pasar el cursor, refactorización) funciona como con cualquier función de TypeScript.

El rendimiento en ejecución es parecido, con dos ventajas documentadas para la Composition API. El sistema de reactividad es el mismo en ambos casos. La documentación de Vue señala que el código en `<script setup>` se minifica mejor, porque el template se compila en una función dentro del mismo ámbito y los nombres de las variables locales se pueden acortar, mientras que el código de la Options API pasa por accesos a propiedades de `this`. Un proyecto que solo usa la Composition API puede además desactivar la Options API con el flag de compilación `__VUE_OPTIONS_API__`, que la elimina del bundle de producción. En la mayoría de las aplicaciones, estas ganancias son pequeñas al lado de cómo se organiza el código.

TypeScript, rendimiento y migración

La migración no es obligatoria. Vue 3 admite las dos API en el mismo proyecto, y en el mismo archivo si hace falta. Un componente de la Options API puede usar un composable llamándolo en un método `setup()` añadido junto a las opciones existentes. No hace falta reescribir componentes de la Options API que funcionan. El camino práctico es escribir los componentes nuevos con `<script setup>` y refactorizar los antiguos solo cuando ya los estés modificando por otro motivo.

Cuándo elegir la Options API. Componentes pequeños o medianos con lógica sencilla. Equipos en los que la mayoría de los desarrolladores está aprendiendo Vue y se beneficia de una estructura explícita. Bases de código ya escritas con la Options API que no necesitan refactorización. Prototipos rápidos, cuando nombrar refs y composables frena más de lo que ayuda la organización.

Cuándo elegir la Composition API. Componentes con varias responsabilidades independientes. Cualquier situación en la que haya que compartir lógica con estado entre componentes (los composables sustituyen a los mixins). Proyectos con TypeScript. Bibliotecas y paquetes de código abierto (los composables son el formato de distribución esperado). Aplicaciones grandes cuyos archivos de componentes superan a menudo las 200 líneas.