vue-pinia-best-practices

Descripción general de la skill vue-pinia-best-practices

La skill vue-pinia-best-practices es una guía enfocada para equipos que trabajan con Vue 3 y Pinia y quieren reducir errores de gestión de estado y tomar mejores decisiones de arquitectura por defecto. No es un tutorial general de Vue. Va directa a los fallos de Pinia que más tiempo hacen perder en proyectos reales: instalar en el momento equivocado, romper la reactividad al desestructurar, problemas de SSR o DevTools en setup stores y dudas sobre qué estado debe vivir en los stores y cuál en la URL.

Para quién encaja mejor esta skill

La skill vue-pinia-best-practices encaja bien para:

• desarrolladores de Vue 3 que ya usan Pinia o están adoptándolo
• equipos que migran desde Vuex o desde stores caseros con reactive()
• desarrolladores que se topan con errores concretos en runtime, como getActivePinia()
• ingenieros frontend que quieren convenciones que escalen más allá de apps pequeñas o de prueba

Es especialmente útil cuando tu aplicación tiene estado compartido, routing, necesidades de SSR, flujos con DevTools o varios contribuidores trabajando a la vez.

Qué trabajo te ayuda a resolver

Usa la skill vue-pinia-best-practices cuando quieras que un asistente de IA revise o genere código de Pinia con menos trampas ocultas. El trabajo real que resuelve no es “explicarme Pinia”, sino “ayudarme a estructurar bien los stores y evitar errores conocidos antes de que lleguen a producción”.

Qué la diferencia de un prompt genérico sobre Vue

Un prompt genérico puede generar código de Pinia que parece correcto, pero que luego falla en la práctica. Esta skill es más sólida porque se centra en un conjunto pequeño de patrones de alto impacto y bien respaldados:

• instalar Pinia antes de cualquier cosa que consuma stores
• evitar acceder a stores en el nivel superior antes de inicializar la app
• devolver todo el estado reactivo desde setup stores
• usar storeToRefs() al desestructurar estado y getters
• mantener en la URL el estado compartible de filtros, no solo en Pinia
• preferir Pinia frente a stores ad hoc en aplicaciones grandes

Lo que no intenta cubrir

Esta skill es deliberadamente acotada. No sustituye la documentación completa para:

• creación avanzada de plugins
• detalles de integración SSR end-to-end específicos de cada framework
• todos los estilos posibles de organización de stores
• patrones de componentes de Vue no relacionados

Si necesitas una configuración exhaustiva y específica de framework, toma esta skill como una capa de protección, no como el plan completo de implementación.

Cómo usar la skill vue-pinia-best-practices

Contexto de instalación de vue-pinia-best-practices

Si tu runner de skills admite instalación basada en repositorios, añade vue-pinia-best-practices desde vuejs-ai/skills igual que harías con otras skills de esa colección. Después de instalarla, el directorio de trabajo importante es:

• skills/vue-pinia-best-practices/

Empieza por:

• SKILL.md

Después, revisa los archivos de referencia que correspondan a tu problema actual.

Lee primero estos archivos según el tipo de problema

La vía más rápida es abrir la referencia que coincida con tu síntoma:

• reference/pinia-no-active-pinia-error.md para fallos de arranque u orden de instalación
• reference/pinia-setup-store-return-all-state.md para problemas de SSR o DevTools en setup stores
• reference/pinia-store-destructuring-breaks-reactivity.md para interfaces que se quedan desactualizadas tras desestructurar
• reference/state-url-for-ephemeral-filters.md para estado de filtros, búsqueda, ordenación y paginación
• reference/state-use-pinia-for-large-apps.md para decisiones de arquitectura
• reference/store-method-binding-parentheses.md para problemas de binding de métodos en stores reactivos que no usan Pinia

El repo es compacto, así que acertar con el archivo adecuado al principio importa más que leerlo todo de forma lineal.

Qué información necesita la skill para ayudar bien

La skill vue-pinia-best-practices funciona mejor cuando le das contexto concreto de implementación, no solo “ayúdame con Pinia”. Incluye:

• tu versión de Vue y si usas Vue 3 con Composition API
• si el store es un store de Pinia o un store reactivo hecho a mano
• si el problema aparece al arrancar, durante la navegación, en templates o tras refrescar
• archivos relevantes como main.ts, la configuración del router, un archivo de store y un componente que lo consuma
• si importan SSR, la visibilidad en DevTools o la persistencia en la URL

Sin ese contexto, el asistente puede darte consejos correctos, pero desalineados con tu caso real.

Convierte un objetivo difuso en un prompt sólido

Prompt débil:

• “Ayúdame a arreglar mi store de Pinia.”

Mejor prompt:

• “Use the vue-pinia-best-practices skill. I have a Vue 3 app with Pinia and Vue Router. I get getActivePinia() during startup when a router guard reads useAuthStore(). Review my main.ts and router file, explain the root cause, and rewrite the setup in the safest order.”

Otro buen ejemplo:

• “Use vue-pinia-best-practices to review this setup store for SSR and DevTools compatibility. Tell me if any reactive state is not returned, what that breaks, and provide a corrected store.”

Flujo de uso práctico de vue-pinia-best-practices

Un flujo fiable para esta skill:

1. Identifica la categoría del síntoma: arranque, reactividad, forma del setup store, estado en URL o arquitectura.
2. Adjunta el conjunto mínimo de archivos que reproduzcan el problema.
3. Pide al asistente que diagnostique usando el archivo reference/*.md correspondiente.
4. Solicita una versión corregida del código junto con una regla breve que puedas reutilizar en otros sitios.
5. Después del primer arreglo, pide una checklist para aplicar el patrón en el resto del repo.

Esto da mejores resultados que pedir una “revisión de buenas prácticas” de una sola vez y sin código.

Úsala para errores de arranque y de orden de plugins

Uno de los usos de más valor de vue-pinia-best-practices es resolver errores de “no active Pinia”. Si guards del router o módulos llaman a stores demasiado pronto, pide al asistente que inspeccione:

• main.js o main.ts
• la creación del router y el registro de guards
• cualquier import en nivel superior que llame a useXxxStore()

La clave casi siempre está en el momento de inicialización, no en la implementación del store en sí.

Úsala para desestructuración segura con la reactividad

Si tu interfaz deja de actualizarse después de extraer valores de un store, pide a la skill que revise si desestructuraste el store directamente. La corrección más probable es:

• mantener las actions desestructuradas directamente si hace falta
• pasar el estado y los getters por storeToRefs()

Es un buen prompt de revisión para cualquier componente que lea muchos valores del store.

Úsala para comprobar SSR y DevTools en setup stores

Si usas defineStore('x', () => {}), pide al asistente que verifique que todo el estado reactivo se devuelve. Esto importa porque el estado omitido puede romper silenciosamente:

• la serialización e hidratación de SSR
• la inspección en Vue DevTools
• la compatibilidad con plugins de Pinia

Esta es una de las mejores razones para usar la skill vue-pinia-best-practices durante code review, no solo cuando estás depurando.

Úsala para decidir dónde debe vivir el estado

Un caso de uso sutil pero valioso de la guía vue-pinia-best-practices es decidir si ciertos datos deberían estar siquiera en Pinia. Pide al asistente que clasifique el estado en:

• estado compartido a nivel de aplicación
• estado local del componente
• estado de vista respaldado por la URL, como filtros, búsqueda, paginación y ordenación

Aquí es donde la skill aporta más valor que snippets genéricos de Pinia, porque ayuda a evitar una arquitectura equivocada antes de que el código crezca.

Mejor patrón de prompt para revisar un repo

Para vue-pinia-best-practices for Frontend Development, un buen prompt de auditoría se parece a esto:

• “Use the vue-pinia-best-practices skill to audit these files for Pinia gotchas. For each issue, label it as install timing, reactivity, setup-store return shape, or state-placement mistake. Show exact fixes and explain production impact.”

Ese enfoque empuja al modelo hacia hallazgos accionables en lugar de consejos abstractos.

Preguntas frecuentes sobre la skill vue-pinia-best-practices

¿La skill vue-pinia-best-practices es buena para principiantes?

Sí, si ya estás construyendo con Vue 3 y has empezado a usar Pinia. La skill es concisa y va primero al problema, así que resulta más fácil de aplicar que una documentación amplia. Los principiantes absolutos quizá sigan necesitando los conceptos básicos oficiales de Pinia para entender stores, getters y actions.

¿Qué problemas cubre mejor la skill vue-pinia-best-practices?

Es especialmente fuerte en un grupo pequeño de problemas comunes y de alto impacto:

• errores de timing de configuración con getActivePinia()
• reactividad rota por desestructuración directa
• setup stores que no devuelven todo el estado
• decidir cuándo el estado en la query de la URL es mejor que el estado en un store
• decidir cuándo compensa usar Pinia en lugar de estado hecho a mano

¿Esto es mejor que pedir ayuda normal sobre Pinia?

Normalmente sí para estos temas concretos. Los prompts corrientes suelen generar código que se ve bien, pero pasan por alto detalles de runtime como el orden de plugins, la serialización SSR o storeToRefs(). La vue-pinia-best-practices skill acota el modelo a errores conocidos y correcciones probadas.

¿Cuándo no debería usar vue-pinia-best-practices?

Sáltatela cuando tu tarea sea sobre todo:

• aprender Vue desde cero
• configuración de despliegue específica de un framework y no relacionada con Pinia
• diseño avanzado de máquinas de estado fuera del alcance del repo
• stacks frontend que no usan Vue

Es una skill de protección focalizada en Pinia, no una skill universal de arquitectura frontend.

¿Ayuda con decisiones de migración desde Vuex?

Indirectamente, sí. El repo respalda explícitamente la idea de que Pinia es la opción por defecto adecuada para aplicaciones Vue grandes y de que Vuex está en modo mantenimiento. Resulta útil al replantear hábitos heredados de Vuex hacia patrones actuales de Pinia, especialmente en torno a stores más simples y mejores herramientas.

¿vue-pinia-best-practices también puede ayudar con stores hechos a mano?

En parte, sí. Una de las referencias cubre problemas de binding de métodos en stores reactivos, y la skill también ayuda a decidir cuándo un estado hecho a mano sigue siendo aceptable. Pero su centro de gravedad está en Pinia, no en bibliotecas de stores personalizadas.

Cómo mejorar la skill vue-pinia-best-practices

Dale a la skill los síntomas exactos del fallo

Para mejorar la calidad de salida de vue-pinia-best-practices, incluye el texto exacto del error, dónde aparece y desde cuándo empezó. Por ejemplo:

• “Error occurs only during router navigation”
• “DevTools does not show a ref from my setup store”
• “UI stops updating after destructuring the store in <script setup>”

Estas pistas encajan de forma directa con las recomendaciones más fuertes del repo.

Incluye el ciclo de vida y el límite entre archivos

Muchos bugs de Pinia en realidad son bugs de timing. Dile al asistente si ese código se ejecuta:

• al importar el módulo
• en setup()
• dentro de un router guard
• durante el bootstrap de la aplicación
• durante la hidratación SSR

Ese contexto ayuda a la skill a distinguir problemas de orden de instalación de bugs normales de componente.

Proporciona fragmentos de código mínimos pero completos

Las mejores entradas suelen incluir:

• main.ts
• un archivo del router si los guards usan stores
• un archivo de store
• un componente que consume el store

No pegues primero todo tu repo. Una reproducción acotada mejora la velocidad del diagnóstico y reduce el relleno genérico.

Pide clasificación, no solo una corrección

Un prompt de alto rendimiento es:

• “Classify each issue by category, explain why it happens, then patch the code.”

Para esta skill, buenas categorías son:

• timing de instalación
• reactividad
• forma de retorno del setup store
• URL vs estado en store
• encaje de escala/arquitectura

Esto hace que la respuesta sea más reutilizable en archivos futuros.

Solicita código antes y después

El paso de instalación de vue-pinia-best-practices es simple comparado con la pregunta real de adopción: ¿puede mejorar el código que genera? La mejor forma de comprobarlo es pedir:

• una muestra de código corregida
• una explicación breve de por qué fallaba el original
• una checklist para aplicar en otros casos

Así conviertes la skill en una herramienta de revisión repetible, no en una respuesta puntual.

Modos de fallo habituales a los que conviene prestar atención

Las salidas más flojas suelen aparecer cuando la entrada está poco especificada. Ejemplos:

• pedir “best practices” sin aportar código ni síntoma
• no indicar si el store es de estilo options o setup
• omitir la configuración del router cuando el problema está relacionado con el arranque
• describir necesidades de persistencia de filtros sin mencionar URLs compartibles

Cuando eso pasa, el asistente puede darte consejos verdaderos que no resuelven tu problema.

Itera después de la primera respuesta

Después de la primera respuesta, haz una segunda pregunta como:

• “Now scan for the same pattern in the rest of my stores.”
• “Convert this fix into a team convention.”
• “Show how this changes if the state should be shareable by URL.”
• “Add SSR and DevTools checks to the review.”

Esta es la forma más sencilla de sacar más partido a vue-pinia-best-practices usage que con una única corrección.

Usa las referencias como reglas de revisión

Los archivos de referencia son lo bastante compactos como para convertirlos en checks de code review del equipo. Ejemplos:

• no usar useXxxStore() en el nivel superior del módulo
• instalar Pinia antes del router si los guards leen stores
• devolver todo el estado reactivo desde setup stores
• usar storeToRefs() al desestructurar estado/getters
• mantener los filtros de vista en la URL cuando importa refrescar o compartir

Esa es la mejor forma, a largo plazo, de mejorar los resultados con vue-pinia-best-practices for Frontend Development: usarla no solo para corregir bugs, sino para imponer mejores decisiones por defecto antes de que aparezcan.