Frontend Guide

Use this page for Core-specific frontend conventions. Use frontend-guidelines for task execution and frontend/development.md for command details.

Scope

Frontend work includes Vue 3 and TypeScript changes under ui/src.

Architecture Fit

Hub pages are server-routed and mounted through Vue entrypoints declared in vite.config.ts. Server-generated boot data is exposed through window.RC.

Feature work usually belongs under:

ui/src/hubs/{management|partner|brand|external|global}/...

Shared UI belongs under:

ui/src/components/

Core Conventions

• Prefer Composition API and <script setup lang="ts"> unless the file already uses another pattern.
• Keep API clients thin wrappers around RequestManager.
• Keep API I/O out of stores and presentation components.
• Use window.RC for page boot data, user context, data sources, and feature flags.
• Keep mocks aligned with backend contracts when using MSW.
• Co-locate local tests as *.test.ts.
• Use type-only imports with type.
• Avoid any; prefer unknown, explicit types, or validated data shapes.
• Preserve hub-specific tenant boundaries and access rules.

Management Hub Edit Gating

Brand detail edit affordances use canUserEditBrandDetails from:

ui/src/hubs/management/brand-detail/tabs/details/components/update.ts

New edit UI in that area should use the same gate unless product explicitly widens access. The backend must enforce the same access; hiding UI is not authorization.

Verification

Run focused frontend checks from nix develop before finalizing (required for agent-driven changes):

npm run format:all
npm run type:check
npm run lint:check
npm run test

format:all and type:check match CircleCI jobs format-ui and typecheck-ui. See .ai/guidelines/frontend-verification.md.

Build when asset output, Vite entries, or production rendering could be affected:

npm run build