bab-app/docs/summaries/handoff-2026-03-19-nuxt-phase7-runtime.md

Session Handoff: Nuxt Migration — Phase 7 Complete

Date: 2026-03-19 Session Focus: Runtime verification and fix Context at Handoff: Low — all pages working in dev, ready for Phase 8

What Was Accomplished

Phase 7 — Runtime Verification & Fixes

All pages now load correctly in dev. Eight issues found and fixed:

Fix 1: QCalendar CSS not imported

• Added css: ['@quasar/quasar-ui-qcalendar/dist/index.css'] to nuxt.config.ts

Fix 2: Appwrite client initialized at module load time with wrong env var pattern

• app/utils/appwrite.ts used import.meta.env.NUXT_PUBLIC_* — not available in Nuxt browser context
• Fix: extracted initAppwriteClient(endpoint, projectId) function, called from plugin after useRuntimeConfig()
• app/plugins/appwrite.client.ts now calls useRuntimeConfig() and guards against empty config

Fix 3: .env.local not loaded by Nuxt 4

• Nuxt 4 auto-loads .env but NOT .env.local
• Fix: copied .env.local → .env (both are gitignored via .env.*)

Fix 4: AddressbarColor plugin missing

• Added 'AddressbarColor' to Quasar plugins list in nuxt.config.ts
• Added ?. guard on q.addressbarColor?.set(...) in app/layouts/default.vue

Fix 5: Static image assets not resolved in Vite

• src="~/assets/oysqn_logo.png" in component props is not processed by Vite (unlike Webpack's ~ convention)
• Fix: copied oysqn_logo.png, oysqn_logo_only.png, oys_lighthouse.jpg to public/
• Updated 4 pages (login.vue, index.vue, signup.vue, pwreset.vue) to use /oysqn_logo.png
• CSS url('~/assets/...') in <style> blocks IS handled by Vite — left unchanged

Fix 6: Quasar SCSS variables ($primary etc.) undefined

• Old Quasar/Webpack auto-imported variables; Vite does not
• Fix: added to nuxt.config.ts:

  vite: {
    css: {
      preprocessorOptions: {
        sass: {
          additionalData: '@use "quasar/src/css/variables.sass" as *\n',
        },
      },
    },
  },
  

• Affects: schedule/view.vue, LeftDrawer.vue, CalendarHeaderComponent.vue, BoatScheduleTableComponent.vue

Fix 7: sass-embedded missing

• Added sass-embedded as dev dependency

Fix 8: PWA service worker caching stale HTML in dev

• Old SW was caching HTML with empty Appwrite config
• Fix: set pwa.devOptions.enabled: false in nuxt.config.ts

Current State

• yarn dev — all pages load correctly
• Login, schedule, admin pages verified working
• Appwrite auth flow functional
• QCalendar renders with correct styling

Files Changed This Session

• bab-app-nuxt/nuxt.config.ts — CSS import, Vite SASS config, AddressbarColor plugin, PWA dev disabled
• bab-app-nuxt/app/utils/appwrite.ts — lazy init via initAppwriteClient()
• bab-app-nuxt/app/plugins/appwrite.client.ts — uses useRuntimeConfig(), guards empty config
• bab-app-nuxt/app/layouts/default.vue — optional chaining on route?.meta?.title and q.addressbarColor?.set()
• bab-app-nuxt/app/pages/login.vue, index.vue, signup.vue, pwreset.vue — logo src path fixed
• bab-app-nuxt/public/ — added oysqn_logo.png, oysqn_logo_only.png, oys_lighthouse.jpg
• bab-app-nuxt/.env — created from .env.local for Nuxt 4 dotenv loading

What NEXT Session Should Do

Phase 8 — Generate & Deploy

1. Update .gitea/workflows/build.yaml — current CI is for the old Quasar app:

   • Remove yarn dlx @quasar/cli ext invoke @quasar/qcalendar step (Quasar CLI, not needed)
   • Add cd bab-app-nuxt or set working-directory for install/build steps
   • Change build command to yarn generate
   • Change artifact path from dist/ to bab-app-nuxt/.output/public/
   • Env vars: CI uses vars.ENV_FILE → needs to write to bab-app-nuxt/.env

2. Test yarn generate in bab-app-nuxt/ — verify .output/public/ is produced

3. Check Ansible deploy playbook — update dist path if needed

Open Questions

• OPEN: Appwrite SDK deprecated API calls — migrate to v14+ signatures? (TS6387 hints in all stores)
• OPEN: task/taskTags/skillTags collections — will they ever be created in bab_prod?
• OPEN: Should .env.local be removed now that .env is in place, to avoid confusion?