oys/bab-app
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects 1 Releases 10 Wiki Activity
Files
e82cdfd00f5b797989f2e2b689baeea27d693743
bab-app/docs/archive/handoffs/handoff-2026-03-18-nuxt-migration-plan.md

8.7 KiB
Raw Blame History

Handoff: Nuxt 3 Migration Plan

Date: 2026-03-18 Type: Architecture / Planning

Decision

Migrate bab-app from Quasar 2 + Vue 3 PWA to Nuxt 3 + Capacitor + FullCalendar. Retain Appwrite backend unchanged. Auth simplified to magic link / email OTP only.

Current Stack (Source of Truth)

  • Quasar 2 / Vue 3 / TypeScript / Pinia / Appwrite
  • Build: PWA only (quasar build -m pwa)
  • Appwrite project: 65ede55a213134f2b688 @ https://appwrite.toal.ca/v1
  • Database: bab_prod
  • Collections: boat, reservation, interval, intervalTemplate, task, taskTags, skillTags
  • 9 Pinia stores, 21 components, 2 layouts, ~20 pages/routes
  • Auth: email token + magic link + password (vue3-google-login present but UNUSED)

Target Stack

  • Nuxt 3 (file-based routing, Nitro, Vite)
  • nuxt-quasar-ui module — keeps all Quasar components during migration, de-risks UI rewrite
  • @fullcalendar/vue3 — replaces @quasar/quasar-ui-qcalendar
  • @capacitor/core + plugins — camera, geolocation (native mobile future)
  • Pinia — unchanged
  • Appwrite SDK — unchanged, via Nuxt plugin
  • Auth: magic link + email OTP only; remove vue3-google-login

Key Architectural Decisions

  • Use nuxt-quasar-ui to avoid a big-bang UI rewrite — keeps q-* components working
  • File-based routing replaces routes.ts — directory structure maps 1:1 to current routes
  • Boot file → Nuxt plugin (appwrite.ts becomes plugins/appwrite.ts)
  • Router guards → Nuxt middleware (auth.ts global middleware)
  • PWA only initially — Capacitor deferred until native camera/GPS features are needed
  • FullCalendar resource-timeline view for multi-boat scheduling (replaces QCalendarResource)
  • FullCalendar non-commercial license confirmed — key: CC-Attribution-NonCommercial-NoDerivatives (OYS is a registered Ontario not-for-profit #000082982)
  • Static output — nuxt generate, served via nginx, consistent with current Ansible deploy
  • TestFlight / App Store deferred — revisit when PWA hits UX or capability limits

Migration Phases (see plan in this file)

Phase 1 — Foundation (1-2 days) ✅ COMPLETE 2026-03-19

Scaffold new Nuxt 3 project alongside existing. Do NOT delete old project until Phase 6 complete.

New project: /home/ptoal/Dev/mobile-projects/bab-app-nuxt/

Tasks:

  • npx nuxi@latest init bab-app-nuxt
  • Add modules: nuxt-quasar-ui, @pinia/nuxt, @vite-pwa/nuxt
  • Configure nuxt.config.ts: Quasar options, Vite aliases, env vars
  • Migrate .env.local vars (VITE_ prefix → NUXT_PUBLIC_ for public vars)
  • Capacitor: DEFERRED — PWA only until native features needed

Phase 2 — Appwrite Plugin + Types (0.5 days)

  • Copy src/boot/appwrite.ts → plugins/appwrite.ts
  • Change export pattern to Nuxt plugin format (defineNuxtPlugin)
  • Provide $appwrite via useNuxtApp()
  • Copy all TypeScript type files verbatim

Phase 3 — Auth (1 day)

  • Migrate stores/auth.ts → stores/auth.ts (Pinia, near-verbatim)
  • Remove all password auth methods (createEmailPasswordSession, etc.)
  • Keep: createMagicURLToken, updateMagicURLSession, createEmailToken, updatePhoneSession
  • Remove vue3-google-login from package.json
  • Create middleware/auth.global.ts — replaces router/index.ts navigation guard
  • Public routes: /login, /signup, /pwreset, /terms-of-service, /privacy-policy
  • Magic link callback: pages/auth/callback.vue — handles ?userId=&secret= params

Phase 4 — Remaining Stores (0.5 days)

All stores are framework-agnostic Pinia — direct copy with minor import path updates:

  • stores/boat.ts
  • stores/reservation.ts
  • stores/interval.ts
  • stores/intervalTemplate.ts
  • stores/task.ts
  • stores/reference.ts
  • stores/realtime.ts
  • stores/memberProfile.ts

Phase 5 — File-Based Routing (Page Scaffold) (0.5 days)

Create empty page files matching Nuxt convention. Route mapping:

Old path Nuxt file
/ pages/index.vue
/boat pages/boat.vue
/certification pages/certification.vue
/profile pages/profile.vue
/checklist pages/checklist.vue
/reference pages/reference/index.vue
/reference/:id/view pages/reference/[id]/view.vue
/schedule pages/schedule/index.vue
/schedule/book pages/schedule/book.vue
/schedule/view pages/schedule/view.vue
/schedule/list pages/schedule/list.vue
/schedule/edit/:id pages/schedule/edit/[id].vue
/schedule/manage pages/schedule/manage.vue
/task PARKED — task feature not migrated (collections absent from bab_prod)
/task/:id/edit PARKED
/admin/user pages/admin/user.vue
/admin/boat pages/admin/boat.vue
/login pages/login.vue
/signup pages/signup.vue
/pwreset pages/pwreset.vue
/terms-of-service pages/terms-of-service.vue
/privacy-policy pages/privacy-policy.vue

Admin route guard: definePageMeta({ middleware: ['auth', 'admin'] }) in admin pages. Schedule manage guard: definePageMeta({ middleware: ['auth', 'schedule-admin'] }).

Phase 6 — Layouts + Global Components (1 day)

  • layouts/default.vue — replaces MainLayout.vue (q-layout, q-header, LeftDrawer, BottomNav)
  • layouts/admin.vue — replaces AdminLayout.vue
  • Migrate components verbatim first; replace Quasar components later if needed:
    • components/BottomNavComponent.vue
    • components/LeftDrawer.vue (OPEN: was listed in agent findings but not in original glob — confirm file exists)
    • components/ToolbarComponent.vue

Phase 7 — Page Migration (3-5 days)

Migrate pages in this order (lowest to highest complexity):

  1. Public pages: login, signup, pwreset, terms, privacy (simple forms)
  2. Profile, Certification, Checklist, Boat (read-only/simple CRUD)
  3. Reference pages
  4. Admin pages (UserAdmin, BoatAdmin — q-table heavy)
  5. Schedule pages (most complex — last)
  6. Task pages — PARKED. Skip until bab_prod collections (task, taskTags, skillTags) are created. Affected: stores/task.ts, components/task/, pages/task/, BottomNav task link, navlinks.ts task entry.

Phase 8 — FullCalendar (2-3 days)

Replace QCalendar with FullCalendar Vue 3.

Packages:

@fullcalendar/vue3
@fullcalendar/core
@fullcalendar/resource-timeline   # multi-boat resource view
@fullcalendar/daygrid             # month/day grid
@fullcalendar/timegrid            # week/day time grid
@fullcalendar/interaction         # drag and drop
@fullcalendar/list                # list view

Mapping:

  • ResourceScheduleViewerComponent.vue → new FullCalendarResourceView.vue
    • Resources = boats (one row per boat)
    • Events = reservations + intervals
    • DnD for admin interval management (replaces IntervalTemplateComponent drag behavior)
  • CalendarHeaderComponent.vue — FullCalendar has built-in header toolbar, simplify or remove
  • BoatScheduleTableComponent.vue — replace with FullCalendar list/grid view

FullCalendar license: open-source plugins are free; resource-timeline requires FullCalendar Premium license ($0 for open-source/non-commercial projects — confirm this applies, otherwise budget ~$200/yr).

OPEN: Confirm if OYS Borrow a Boat qualifies for FullCalendar open-source license.

Phase 9 — Capacitor (1 day)

  • npx cap add ios / npx cap add android
  • Install plugins (not wired to features yet, just scaffold):
    • @capacitor/camera
    • @capacitor/geolocation
  • Create composables/useCamera.ts and composables/useGeolocation.ts
    • Detect Capacitor.isNativePlatform() and fall back to browser APIs on web
  • Update nuxt.config.ts ssr: false (Capacitor requires SPA mode)
  • capacitor.config.ts: webDir: '.output/public'

Phase 10 — CI/CD (0.5 days)

Update .gitea/workflows/build.yaml:

  • Replace quasar build -m pwa with nuxt build
  • Output dir: .output/public/ (static) or .output/ (server)
  • Ansible deploy: serve .output/public as static site (nginx), same as current

Open Questions

  • OPEN: Does OYS qualify for FullCalendar non-commercial license? (resource-timeline is premium)
  • OPEN: Confirm LeftDrawer.vue exists in src/layouts/ or src/components/ — agent referenced it but not in initial glob
  • OPEN: Is Capacitor native app publishing (App Store / Play Store) in scope, or just Capacitor for future native API access with PWA as primary delivery?
  • ASSUMED: SSR is not needed — Appwrite client SDK runs browser-side; deploy as SPA/static
  • ASSUMED: Nuxt deployed as static output (not Node server) — consistent with current nginx/Ansible deploy

Effort Estimate

Phase Days
1-4 (Foundation, Plugin, Auth, Stores) 3
5-6 (Routing, Layouts) 1.5
7 (Page migration) 4
8 (FullCalendar) 2.5
9 (Capacitor) 1
10 (CI/CD) 0.5
Total ~12.5 days