Frontend V2 Patterns
Developmentfrontend-v2-patternsFrontend V2 Patterns is an Agent Skill for development published in the rommapp/romm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Cross-cutting feature patterns for the RomM v2 frontend — error/snackbar handling, loading & skeleton states, real-time Socket.IO updates, UI state persistence (URL vs localStorage vs ephemeral), pagination/infinite scroll, forms & validation, permissions (useCan), and destructive confirmations. Use when wiring up a v2 feature's behavior (not just its markup). Trigger when implementing data flows, dialogs, forms, toggles, or permission gating under frontend/src/v2/.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/rommapp/romm/blob/HEAD/.claude/skills/frontend-v2-patterns/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/frontend-v2-patterns, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
RomM v2 — Architecture Patterns
How v2 features behave. Each pattern has one canonical mechanism — don't invent a parallel one.
A. Errors & snackbars
- Single channel:
useSnackbar()(src/v2/composables/useSnackbar/) withsuccess | error | warning | infomethods. It emitssnackbarShow;NotificationHoststacks toasts. - The call site decides what's significant — no global "wrap-every-promise" magic.
- Field validation errors render in-place, never as a snackbar.
- Auth (401/403) is handled by the axios interceptor; no per-call-site checks.
- Successful critical actions →
successsnackbar. Routine optimistic toggles → silent on success,erroron failure. - Don't snackbar every rejected promise.
B. Loading states
- Skeleton (
RSkeletonBlock) for first load of a view with known layout — mimic the real shape so the layout doesn't jump. - Inline
:loadingon the control itself for in-flight actions (RBtn,RTextField,RSelect). Never put an externalRSpinnernext to a button that has its ownloading. RSpinnerinline when what's loading isn't a control with nativeloading.- Determinate progress (%): use
RProgressLinear— no rawv-progress-linear. - Empty state ≠ loading state. Zero items is its own UX (message, illustration, optional CTA).
- Optimistic toggles show no spinner: flip immediately; on failure, revert + snackbar.
RBtnshipsloadingDebounce={200}— actions resolving under 200ms never paint a spinner; loading→not-loading is immediate.
C. Real-time updates (Socket.IO)
- One instance:
src/services/socket.ts. Nevernew io(). - New consumers go through (or build) a
useSocketEvent(event, handler)composable for typed subscriptions with automatic mount/unmount cleanup (this composable is still debt — today consumers wiresocket.on/offby hand). - Ownership rule: state living only while a view is open → subscribe in the view; state that must outlive a view (e.g. scan badge in navbar) → a Pinia store subscribes globally and views just read.
- Reconnection is socket.io's job — don't roll your own.
D. UI state persistence — three layers
- Persistent preferences (theme, language, gallery defaults like
groupRoms/boxartStyle, Home panels) →useUISettings(localStorage + backenduser.ui_settingstwo-way sync). Add a key toUI_SETTINGS_KEYS. - Bookmarkable session state (active filters, search query, sort, current tab in detail views) → URL query params. Anyone copying the link reproduces what they see. Active gallery filter must be in URL.
- Ephemeral session state (open dialog, hover, expansion) →
refif local, Pinia store if cross-component within the session.
Don't push state into useUISettings "so it persists" — follow the rule above.
E. Pagination & infinite scroll
LoadMore(RBtn+RSpinner+ IntersectionObserver) is the canonical fallback when virtualization stalls.RVirtualScroller(src/v2/lib/structural/, wrappingv-virtual-scroll) is the substrate for large lists/grids.- Page size lives in the store (
fetchLimit); not user-configurable for now. - Scroll restoration on back-nav: Vue Router
scrollBehavior+ Pinia in-session offset. URL holds filters/sort/search but not scroll offset.
F. Forms & validation
- Use the
RFormprimitive (wrapsv-form: Enter-to-submit when valid, scroll-to-first-error after a failedvalidate()). Never usev-formdirectly. - Native Vuetify rules — no Zod/Yup. Rules are arrays of
(v) => true | string. - Reusable rules in
src/v2/utils/validation.ts(required(msg?),email,asciiOnly,lengthBetween,usernameLength/Chars,passwordLength). Utility code may calli18n.global.t(...)(the no-i18n rule covers lib primitives, not utils). - Submit pattern:
await formRef.value?.validate()before the API call; submit button uses:loading="submitting"; errors → snackbar; field errors stay in-place via:error-messages.
G. Permissions
- Action vocabulary
domain.action(rom.upload,rom.delete,library.scan,user.create,app.admin) insrc/v2/composables/useCan/actions.ts. - Scope vocabulary:
type PermissionScope = | { kind: "global" } | { kind: "platform"; id: number } | { kind: "collection"; id: number } | { kind: "rom"; id: number }; useCan(action, scope?)returnsComputedRef<boolean>, reactive topermissionsStore.grants. Without scope: "can do this anywhere."stores/permissions.tsholds normalised grants, hydrated fromauthStore.user.rolevia the role-map (installPermissionsHydration()inAppLayout); a future/permissions/mewill replace it.v-ifto hide options a user shouldn't see;:disabledwith tooltip when the option must be visible but blocked.- Backend is source of truth — frontend is a UX hint. Never bypass with inline
user.role === "...". All grants are pre-loaded (nouseCanAsync).
H. Destructive confirmations
Three friction levels:
- Low / High → shared composite
ConfirmDialog(components/shared/) opened viauseConfirm({ title, body, confirmText, tone, requireTyped }) => Promise<boolean>(mounted once inGlobalDialogs). - Medium → a feature composite when the flow needs extra options (e.g.
DeleteRomDialogwith per-item filesystem checkboxes).
Common rules:
- All destruction goes through a dialog — no silent destructive action.
- Confirm button is danger-toned; focus starts on Cancel; Enter cancels.
- Success → success snackbar or navigate away, dialog closes. Error → error snackbar, dialog stays open. During action → confirm shows
:loading, cancel disabled. - The destructive control respects
useCan(action, scope). - No "don't ask again." Type-to-confirm (
requireTyped) is required when the action affects the filesystem.