Frontend Standards

Standards that apply to all Conduction Nextcloud apps. These are enforced via ESLint rules and code review.

OpenRegister Dependency Check

All apps that depend on OpenRegister (everything except nldesign and launchpad) must show an empty state when OpenRegister is not installed, instead of a broken UI.

Backend (SettingsController)

The settings endpoint must return openRegisters and isAdmin fields:

use OCP\App\IAppManager;
use OCP\IGroupManager;
use OCP\IUserSession;

// In constructor: inject IAppManager, IGroupManager, IUserSession

// In the index() / settings GET endpoint:
$user    = $this->userSession->getUser();
$isAdmin = $user !== null && $this->groupManager->isAdmin($user->getUID());

return new JSONResponse([
    'openRegisters' => in_array(needle: 'openregister', haystack: $this->appManager->getInstalledApps()),
    'isAdmin'       => $isAdmin,
    'config'        => $this->settingsService->getSettings(),
]);

The controller should also have the standardized getObjectService() and getConfigurationService() methods for lazy-loading OpenRegister services (see softwarecatalog/opencatalogi for reference).

Frontend Store (Pinia)

The settings store must expose:

• openRegisters: false in state
• isAdmin: false in state
• hasOpenRegisters getter
• getIsAdmin getter
• Read both from the API response in fetchSettings()

Frontend App.vue

Three-state conditional in the template:

1. OpenRegister missing (storesReady && !hasOpenRegisters): NcEmptyContent inside NcAppContent with class open-register-missing — no sidebar, no navigation
2. Normal (storesReady && hasOpenRegisters): full app with menu, content, sidebar
3. Loading (else): centered NcLoadingIcon

The empty state uses:

• NcEmptyContent with :name and :description props
• #icon slot with the app's own icon (imagePath('<appname>', 'app-dark.svg'))
• #action slot with NcButton linking to app store (admin) or text hint (non-admin)
• Admin detection comes from the backend (settingsStore.getIsAdmin), NOT from OC.isAdmin (which doesn't exist)
• App store URL: generateUrl('/settings/apps/integration/openregister')

Centering

The NcAppContent wrapper needs .open-register-missing class with flex centering. This goes in src/assets/app.css (not in a Vue <style> block).

CSS Scoping

Rule: No unscoped <style> in Vue files

All <style> blocks in .vue files must use the scoped attribute. Global styles go in src/assets/app.css and are imported in main.js.

Why: Unscoped styles leak into other components and cause hard-to-debug styling issues. The scoped attribute ensures styles only affect the component they belong to.

Enforced by: ESLint rule vue/enforce-style-attribute:

'vue/enforce-style-attribute': ['error', { allow: ['scoped'] }]

Where global styles go

• src/assets/app.css — app-wide overrides (e.g., library component fixes, empty state centering)
• css/ directory — styles loaded by Nextcloud outside of webpack (e.g., dashboard widget icons)
• Import in main.js: import './assets/app.css'

Routing History Mode

Path-based Vue Router history (createWebHistory) is the fleet convention. Hash-based (createWebHashHistory, #/… URLs) is the thing being migrated away from, not a valid alternative for new apps.

Why path, not hash: hash routing needs zero server-side work (everything after # never reaches the server) at the cost of permanently ugly URLs and broken #-based deep links whenever an app also wants to use the fragment for something else (e.g. anchors). Path routing gives real, shareable, refresh-safe URLs, but the trade is real: it needs a server-side catch-all, or a direct hit on a deep client route (e.g. a bookmark, a page refresh) 404s.

A path-history app with no working catch-all is not ahead of the convention — it is broken, and worse than staying on hash. Do not flip createWebHashHistory → createWebHistory in main.js without first confirming (and, ideally, live-testing a hard reload of a deep route against) one of the two sanctioned catch-all mechanisms below.

Two sanctioned ways to get the catch-all

1. \OCA\OpenRegister\AppHost\Routes::standard($extra) — the shared route-table builder. Call it from appinfo/routes.php and it appends a /{path} catch-all (excluding /api/*) to whatever app-specific routes you pass as $extra. This is the preferred mechanism for any app that already depends on OpenRegister. Reference: docudesk/appinfo/routes.php.
2. A hand-rolled catch-all route in appinfo/routes.php that matches /{path} (or equivalent) and excludes /api/*, dispatching to a controller action that just renders the SPA shell (e.g. dashboard#catchAll, ui#dashboard). Reference: openconnector/appinfo/routes.php's ui#dashboard route — pre-existing from an earlier, unfinished migration, verified working and now wired up to the frontend.

Either way, main.js's createWebHistory(...) call needs no other change — the catch-all is purely a backend routing concern.

Gate: lint-router-history-mode.sh

.github/hydra-gates/scripts/lint-router-history-mode.sh checks both halves of this convention per app: router mode in src/main.js, and (for apps already on path history) catch-all presence in appinfo/routes.php. A missing catch-all on a path-history app is an unconditional failure regardless of gate mode — it is a real bug, not an in-progress migration state.

# Single app, from that app's repo root:
bash ../.github/hydra-gates/scripts/lint-router-history-mode.sh

# Fleet-wide summary, from apps-extra/:
bash .github/hydra-gates/scripts/lint-router-history-mode.sh --fleet

As of 2026-08-15 (19 apps checked, --fleet): openconnector is on path history with a verified catch-all; decidesk, docudesk, hermiq, hrmq, openbuild, portaliq, procest, scholiq, shillinq were already on path history; doriath, larpingapp, opencatalogi, openregister, pipelinq, softwarecatalog, zaakafhandelapp remain on hash history, not yet converted. The gate runs in WARN mode (HYDRA_ROUTER_HISTORY_GATE_MODE=WARN, the default) — it reports hash-history apps without failing CI — until every remaining app has a verified catch-all and is converted; flip to BLOCK only after that.

Admin Detection

Never use OC.isAdmin — it doesn't exist in Nextcloud's frontend JavaScript API. Instead:

• Pass isAdmin from the backend via the settings endpoint using IGroupManager::isAdmin()
• Store it in the Pinia settings store
• Access via computed property in components

Reference Implementation

Pipelinq is the reference implementation for all these patterns:

• Backend: pipelinq/lib/Controller/SettingsController.php
• Store: pipelinq/src/store/modules/settings.js
• App.vue: pipelinq/src/App.vue
• CSS: pipelinq/src/assets/app.css
• ESLint: pipelinq/eslint.config.js

Gotchas that trip mechanical gates

A few surface patterns have empirically caused review round-trips because they interact badly with either the Hydra gate regexes or the NC framework. Avoid them.

Avoid arrow functions inside Vue attribute values

Vue templates like <NcSelect :reduce="(o) => o"> contain a > character inside an attribute value. Some downstream tooling — including hydra-gate-nc-input-labels on Hydra main — assumes attribute values do not contain > and truncates the tag prematurely. A tag whose :input-label prop lives on a line AFTER :reduce will falsely trip the gate.

Two workable patterns:

<!-- Preferred: order matters — labels first, complex bindings last -->
<NcSelect
    :options="opts"
    :input-label="t('app', 'Level')"
    :reduce="(o) => o"
    :clearable="false" />

<!-- Alternative: named function, no arrow -->
<NcSelect
    :options="opts"
    :reduce="function (o) { return o }"
    :input-label="t('app', 'Level')" />

Reference case: opencatalogi PR #79 round-3.

Cascade error handling — one key, not four

// ❌ Cascading through 4 possible error-body shapes is a smell — the backend is drifting.
const msg = body?.data?.error || body?.error || body?.message || `HTTP ${res.status}`

// ✅ Per ADR-050, the backend returns `{message, error?}`. One fallback.
const msg = body?.message || `HTTP ${res.status}`

If the backend is drifting, fix the backend to align with ADR-050 rather than layering more fallbacks in the frontend.

CSRF on raw fetch() calls

Raw fetch() to a Nextcloud AppFramework route (/apps/{appid}/api/...) does NOT auto-send requesttoken. Options, in order of preference:

1. Use @nextcloud/axios (auto-injects requesttoken via its interceptor).
2. Add OCS-APIRequest: true to headers — satisfies NC's CSRF bypass (Request::passesCSRFCheck()).
3. Manually set requesttoken via getRequestToken() from @nextcloud/auth.

Reference case: opencatalogi PR #79 F8 — delete-modal fetch had none of these, and the moment the backend dropped @NoCSRFRequired the call would have started 412ing.