ADR-001: Stack de Frontend — Vue 3 + Vite SPA (sin SSR)

Date: 2026-07-25 Status: Accepted

Context

Se evaluaron 3 opciones de stack de frontend (doc/plans/2026-07-25-frontend-stack-options.md): React/Next.js, Vue/Nuxt, y Svelte/SvelteKit. El cliente tiene experiencia profunda en Vue y preguntó explícitamente si convenía moverse a alguna de las otras dos dado el estado de la tecnología en 2026.

Dos restricciones adicionales, no consideradas en el documento original, resultaron decisivas:

• El backend vive en AWS, separado del frontend, expuesto por REST/JWT.
• El frontend se deploya en Firebase Hosting, que es hosting estático.
• La aplicación es un panel interno autenticado (no un sitio público) — no hay requisito de SEO ni de first-paint de contenido público.

Decision

Se adopta Vue 3 + Vite, como Single Page Application (SPA) pura, sin SSR, con:

• UI: Nuxt UI v4 como librería de componentes (usable fuera de Nuxt), o alternativamente Naive UI / Vuetify si se prioriza un look distinto — a definir con ui-engineer.
• Estado servidor: TanStack Query for Vue (@tanstack/vue-query).
• Estado cliente: Pinia.
• Routing: Vue Router (permisos por ruta resueltos contra la matriz L/E/B del Análisis Funcional, sección 2).
• Deploy: Firebase Hosting, mismo patrón estático que doc/site (sin Cloud Functions ni Cloud Run).

No se usa Nuxt en modo SSR. Nuxt (o Next.js, en la opción descartada) agrega valor real vía Server Components / streaming SSR cuando hay contenido público que necesita SEO o first-paint rápido. Esta app no tiene esa necesidad — está atrás de login. Usar SSR acá solo agregaría complejidad de infraestructura (runtime de servidor en Cloud Functions/Cloud Run) sin ningún beneficio a cambio, y complicaría innecesariamente el hosting 100% estático que ya funciona bien para el portal de documentación.

Rationale — por qué no Opción 1 (React) ni Opción 3 (Svelte)

• vs. React/Next.js: el ecosistema más grande de React no compensa perder la experiencia profunda del equipo en Vue. Nuxt UI v4 (gratis desde 2026) y frameworks tipo Soybean Admin cubren el mismo terreno de "menús dinámicos por permisos" que necesitamos. Las Server Components de Next.js — su ventaja más citada en 2026 — no aplican a un panel privado sin SEO.
• vs. Svelte/SvelteKit: el modelo de reactividad "runes" de Svelte 5 es conceptualmente equivalente a la Composition API de Vue que el equipo ya domina — no hay una simplificación real. La ventaja de bundle más chico es teórica hasta que se mida un problema real de conectividad en algún PDV. A cambio, se pierde ecosistema maduro y pool de contratación.

Alternatives Considered

• Opción 1 — Next.js 16 + React 19 + shadcn/ui: descartada. Mayor ecosistema, pero sin ganancia neta para este proyecto específico; abandona la experiencia Vue del equipo sin compensación real.
• Opción 3 — SvelteKit 2 + Svelte 5: descartada. Ganancia de performance no comprobada como necesaria; pierde ecosistema y pool de contratación sin necesidad.
• Nuxt 4 en modo SSR: descartada específicamente por el mismatch con Firebase Hosting (estático) + AWS backend — agregaría runtime de servidor sin beneficio, dado que no hay contenido público que necesite SEO.

Consequences

• Positivo: se conserva y capitaliza la experiencia Vue existente del equipo. Deploy simple (Firebase Hosting estático, mismo patrón que doc/site, sin Cloud Functions). Nuxt UI v4 da 125+ componentes gratis (MIT) para armar los ABMs rápido.
• Negativo: si en el futuro se necesita SEO público (por ejemplo, una landing pública para algún país), esta app SPA no lo resuelve — habría que evaluar un proyecto Nuxt SSR aparte para esa necesidad puntual, no mezclarlo con el panel interno.
• Neutral: al no usar Nuxt como framework completo, el equipo arma manualmente lo que Nuxt daría gratis (file-based routing, auto-imports) usando Vue Router + Vite — más control, un poco más de configuración inicial.

Next Steps

• frontend-dev / ui-engineer arrancan el scaffold real del proyecto sobre esta base.
• Actualizar doc/environments/dev.md y start-dev.sh para levantar también el frontend real una vez exista el repo.
• architect define el ADR de arquitectura de backend (AWS) — pendiente.