Ga naar hoofdinhoud

CnAppRoot

Top-level wrapper for manifest-driven Conduction apps. Provides the manifest, custom-component registry, page-type registry, and translate function to descendants via provide / inject. Orchestrates three rendering phases: loading → dependency-check → shell.

CnAppRoot is the full-shell convenience for the JSON manifest renderer. Apps that want manifest-driven pages but their own root layout can skip CnAppRoot and use CnPageRenderer / CnAppNav directly with explicit props.

Wraps: NcContent, NcAppContent, CnAppLoading, CnDependencyMissing, CnAppNav

Phases​

PhaseWhenDefault renderingOverride slot
loadingWhile isLoading is true<CnAppLoading />#loading
dependency-missingAfter loading; an unresolved HARD dependency in manifest.dependencies<CnDependencyMissing />#dependency-missing
setupHARD dependencies satisfied; a required manifest.setup step is unmet<CnSetupWizard :cancellable="false" />#setup
shellManifest loaded + all HARD dependencies satisfied + no required setup step unmet<CnAppNav /> + default slot content#menu, default slot, #header-actions, #sidebar, #footer

Dependency status is resolved by useAppStatus — one call per id in manifest.dependencies, cached for the page lifetime.

HARD vs SOFT dependencies​

Each entry in manifest.dependencies is either a string (a HARD dependency — the app cannot run without it) or an object { id, required?, name? } where required: false marks a SOFT (optional) integration. required defaults to true, so existing string-only manifests behave exactly as before.

"dependencies": [
"openregister", // HARD: blocks the shell when missing
{ "id": "deck", "required": false, "name": "Deck" } // SOFT: dismissible in-shell notice
]
Unresolved behaviour
HARD (string, or required not false)Blocks the shell — phase dependency-missing, <CnDependencyMissing> full-page screen.
SOFT (required: false)Never blocks. Renders a dismissible NcNoteCard banner inside the shell carrying the same install/enable action. Dismissal persists per app+dependency under localStorage key cn-soft-dep-dismissed:{appId}:{depId}.

In-place install / enable​

Both dependency surfaces (CnDependencyMissing and the or-missing guard) and every soft-dependency banner render an admin-aware action driven by useAppInstaller: an admin clicks Install and enable (not installed) or Enable (installed but disabled) and nc-vue downloads, installs and enables the app via Nextcloud's install endpoint — the NC34+ bundled-appstore OCS API, falling back to the legacy settings/apps/enable route on ≤NC33 — then reloads. Non-admins — who cannot hit that admin-only endpoint — see "ask your administrator to enable {name}" copy instead of a dead-end link. On failure the error shows inline and the original store link stays as a fallback.

When no server-side dependency_statuses initial-state is present and the JS heuristic cannot distinguish "not installed" from "installed but disabled", the action defaults to the Install and enable label — a genuinely-missing app must never be mislabelled Enable.

The or-missing guard (the capabilities check driven by the requiresApps prop) now renders English default copy for the app-availability.title / app-availability.description / app-availability.action keys when the translate prop leaves them unchanged, so the raw keys never render.

First-time setup (ADR-042)​

When the manifest declares a setup block, CnAppRoot resolves its status through useSetupStatus and surfaces CnSetupWizard on one of two paths. No new props — both are driven entirely by the manifest and the server's GET /apps/{appId}/api/setup/status response.

PathConditionBehaviour
GatingA required step is unmetThe whole shell is replaced (phase === 'setup'). The wizard is mounted with cancellable="false" — no Cancel button, no ESC, no backdrop close — because there is nothing useful to fall back to. Override with the #setup slot.
Non-gatingEvery required step is met, but at least one actionable optional step isn'tThe shell renders normally and the wizard auto-opens once as a dismissible overlay (cancellable="true").

Both instances receive completedStepIds, so a wizard mounted mid-way resumes at the first genuinely unmet step rather than re-asking what a previous session already persisted. A fresh setup (nothing done yet) always starts at step one so a leading info / welcome step is seen.

"Actionable" excludes info and summary steps. The server has nothing to persist for those, so they report done: false forever; counting them would auto-prompt every user on every version, including fully-configured ones.

"Actionable" also excludes run-action steps marked onDemand: true: they run only when the user asks, so they never open the wizard. See On-demand steps.

A step whose requires names an app that is not installed and enabled is not applicable. The wizard skips it, so it neither opens the wizard nor, when required, gates the app. See Missing apps.

Dismissal​

The non-gating overlay records dismissal in localStorage under:

cn-setup-wizard-dismissed:{appId}:{manifest.setup.version}
  • Both Cancel and Finish write the flag. Finishing counts as dismissal because Next is allowed to skip optional steps — a user can legitimately reach Finish with an optional step still un-done, and the server will keep reporting it unmet. Without this, completing the wizard would re-prompt on every page load while cancelling bought permanent peace.
  • Because the key includes setup.version, bumping it in the manifest (e.g. after adding a new optional step) re-prompts everyone exactly once.
  • Storage failures (private mode, disabled storage) are non-fatal: dismissal falls back to a session-only flag.
  • On @complete the overlay stays mounted so CnSetupWizard's result phase ("Setup complete.") is visible; its Close button drives the unmount.

The walkthrough waits for setup​

When the manifest also declares a walkthrough, the tour is held back until the setup status has loaded and the non-gating wizard is closed, so on a first run the wizard comes first and the tour starts when the wizard is cancelled or finished. See CnWalkthrough.

Usage​

<template>
<CnAppRoot
:manifest="manifest"
app-id="decidesk"
:is-loading="isLoading"
:custom-components="customComponents"
:page-types="pageTypes"
:translate="translate"
:permissions="permissions">

<!-- Optional overrides -->
<template #loading>
<MyBrandedLoadingScreen />
</template>
</CnAppRoot>
</template>

<script>
import { CnAppRoot, useAppManifest, defaultPageTypes } from '@conduction/nextcloud-vue'
import bundledManifest from './manifest.json'
import MyReportPage from './views/MyReportPage.vue'

export default {
components: { CnAppRoot },
setup() {
const { manifest, isLoading } = useAppManifest('decidesk', bundledManifest)
return {
manifest,
isLoading,
customComponents: { /* keys referenced by page.component for type:"custom" pages */ },
pageTypes: { ...defaultPageTypes, report: MyReportPage },
translate: (key) => t('decidesk', key),
permissions: ['decisions.read', 'decisions.write'],
}
},
}
</script>

Props​

PropTypeDefaultDescription
manifestObject— (required)Reactive manifest. The renderer reads manifest.dependencies and manifest.menu; descendants inject('cnManifest').
appIdString— (required)Nextcloud app id. Forwarded to NcContent as app-name and to CnDependencyMissing.
appDisplayName (app-display-name)String''Human-readable name shown in the Nextcloud top bar. When set it overrides the technical appId so a virtual app shows its own name (e.g. "Pet Store") instead of the host app id. The user settings dialog, the setup wizard and the credentials section show it through the app's translate; without it they show the name Nextcloud's app menu gives (localised), else the id with a capital, never the bare id. The top bar's own name, which also keys the stored list-pane width (pane-list-size-<name>), stays untranslated so a reader's pane width survives a language switch.
persistManifestDeltaFunctionnullOptional persistence hook for in-app editing (ADR-041). Called with the minimal manifest delta when the user saves an edit. When omitted, Save updates the rendered manifest in memory but persists nothing — wire it to the Buildiq app-override endpoint to make edits durable. When Buildiq is reachable for the user, CnAppRoot surfaces a Conduction-orange edit button (CnBuildiqEditButton) top-right of the content and provides a shared cnManifestEditor; the body grid becomes drag/resizable in edit mode. Emits @manifest-save(delta).
dataSourcesObject | nullnullApp registers/schemas for the in-app pages editor (ADR-041). Lets the Edit-pages modal offer Register / Schema / Columns dropdowns for index/detail pages instead of free-text slug inputs, so a created page actually renders a table. Shape: { registers: [{ value, label, schemas: [{ value, label, columns: string[] }] }] }. Provided to descendants as cnDataSources; when omitted the editor falls back to free-text register/schema fields. A snapshot — captured once, so it cannot show anything created after boot. Prefer dataSourcesLoader.
dataSourcesLoader (data-sources-loader)Function | nullnullAsync loader for the same data, re-invoked every time a pages-editor modal opens: async () => ({ registers: [...] }). Because provide() runs once, the static dataSources snapshot can never change — so a register or schema created after the app booted (in another tab, the OpenRegister UI, or via the API) would never appear in the dropdowns. A loader fixes that with no page reload, and moves the fetch off the app-boot path onto the far rarer editor-open path. When both props are given, dataSources seeds the initial list and the loader's result replaces it on the first refresh.
routerViewKey (router-view-key)String | Number'cn-router-view'Remount key for the routed <router-view>. Hosts that rebuild the router at runtime (e.g. the Buildiq builder adding a page mid-edit) bump this after the rebuild so the view drops its stale component-instance cache and mounts the new routes — a Vue Router 3 matcher swap alone resolves the new hrefs but leaves SPA-navigation to a just-added route rendering a blank view. Keep the default for static apps: the key is stable across ordinary navigation, so the view is never needlessly remounted (and the shell / teleported modals are untouched).
isLoadingBooleanfalseWire to useAppManifest().isLoading. Apps using only the bundled manifest skip the loading phase.
customComponentsObject{}Registry consumed by CnPageRenderer for type: "custom" pages and slot overrides. Provided as cnCustomComponents.
formattersObject{}Cell-formatter registry — map of formatter-id → (value, row, property) => string|number. Resolves the pages[].config.columns[].formatter ids that index / logs pages declare, so per-column value formatting lives in small pure data functions instead of bespoke type:"custom" table views. Provided to descendant CnDataTable / CnCellRenderer as cnFormatters. See migrating-to-manifest → Column formatters.
cellWidgetsObject{}Cell-widget registry — map of widget-id → Vue component, rendered for a column that declares pages[].config.columns[].widget. The component receives { value, row, property, formatted, ...widgetProps }. The library ships one built-in id, "badge" (renders CnStatusBadge); consumer entries cover everything else (status pills, inline toggles, link cells, …). Provided to descendant CnDataTable / CnCellRenderer as cnCellWidgets. See migrating-to-manifest → Column widgets.
kbSearchProvidersObject{}Pluggable knowledge-base search providers (#91 Wave 3) — map of provider-key → { search(query, opts), externalOpen? }, merged OVER the library built-in default (endpoint) provider and provided to descendant CnKbSearchWidget as cnKbSearchProviders. A kb-search widget picks its provider via content.provider; an app talking to a bespoke KB backend (the xwiki proxy) registers its client here — the library ships only the seam. See CnActionButtons / kb-search.
pageTypesObject | nullnullMap of pages[].type → Vue component. Provided to descendant renderers as cnPageTypes. When omitted, the renderer falls back to defaultPageTypes.
translateFunctionidentityApp-supplied translator — typically (key) => t(appId, key). Named translate (not t) to avoid shadowing the global t() mixin. Provided as cnTranslate.
environmentString''Environment this instance is: development, test, acceptance or production. Wins over the active organisation's environment field. A non-production value shows a CnEnvironmentBanner and prefixes the tab title.
languageStringuser's languageThe language labels are shown in. Defaults to the user's Nextcloud language; a preview can pass another. The label lookup tries manifest.i18n.labels[language] (then its base, en_GB to en), then the host translate, then the text as written. See Manifest labels.
diagnosticsFunctionnullListener for diagnostics: called with one report per request, render error, unknown component and binding problem ({ kind, at, pageId, ... }), and provided as cnDiagnostics. Without it no report is built. See Diagnostics channel.
notificationLabels (notification-labels)Object{}Labels for the app's notification rules in the user-settings notification pane, keyed <schema>.<key> or <key>. Values are translated strings or per-locale maps. A rule without a label reads as its key split into words, never as the raw key. Provided as cnNotificationLabels.
permissionsArray<string>[]Permission strings the current user holds. Forwarded to CnAppNav for menu filtering.
userSettingsTitleString''Title shown at the top of the hosted NcAppSettingsDialog. Empty (the default) resolves to "User settings" from the library catalogue ("Persoonlijke instellingen" in Dutch), then the app's translate. Override per app to brand the modal (e.g. 'Decidiq preferences').
userSettingsEyebrowString''Deprecated and ignored: the board user-settings dialog (DqPersoonlijkeInstellingen) draws its title alone, at the top of its navigation column.
userSettingsSubtitleString''Deprecated and ignored, for the same reason.
userSettingsNextcloudLinksArray[]Board look: Nextcloud's own personal settings, listed first in the user-settings navigation as links, [{ label, section? | href?, icon? }] (section is a personal settings section id, opened at /settings/user/<section>). With any, the app's sections sit under one entry named after the app. Labels go through the app's translate.
userSettingsSectionsArraynullThe sections of the user-settings modal, in the order they are drawn: app (the app's own slot content), notifications, credentials, walkthrough, integrations. A key left out is not drawn, so ['app', 'credentials', 'walkthrough'] hides the notifications pane and the integrations section. The app's slot content always renders; without app it comes first. null keeps the defaults: every section after #user-settings-sections content, or only the #user-settings content and the integrations section. See User-settings modal.
adminSettingsTitleString''Title shown at the top of the admin-settings NcAppSettingsDialog. Empty (the default) resolves to translate('Administration'). Override per app (e.g. 'Pipelinq administration').
requiresAppsArray<string>['openregister']App ids that MUST be installed for the host app to function. Checked against the OCS capabilities API on mount. When any required app is missing, CnAppRoot renders the or-missing slot (default <NcEmptyContent>) instead of the renderer. Pass [] to opt out (e.g. launchpad, the docs/styleguide app). See App-availability guard.
brandObject | nullnullThe brand block ({ logo?, emblem?, name?, caption?, alt?, placement? }) the board look draws at the start of Nextcloud's header. Empty falls back to the manifest's nav.brand.
look''|'board'|'nextcloud'''The look the app is drawn in. Empty falls back to the manifest's top-level look, then nextcloud. Provided to descendants as cnLook; in the board look the library's empty states draw as the card-size CnWidgetEmptyState.
initialOrganisationUuidString | nullnullSeed value for the multi-tenancy provider's activeOrganisationUuid. CnAppRoot calls provideTenantContext(initialOrganisationUuid, initialOrganisation) on mount, so consumers wired to useTenantContext see the seeded tenant from the first render. Single-tenant deployments leave both props null.
initialOrganisationObject | nullnullOptional resolved organisation entity matching initialOrganisationUuid. Stored on activeOrganisation so downstream components (CnTenantBadge, CnFormDialog auto-fill) have the name/icon available immediately without a follow-up fetch.
chatAppIdString'openregister'Backend app id the hosted CnAiCompanion targets for its chat/agent HTTP calls (see chatApiBase / DEFAULT_CHAT_APP_ID). Override (e.g. 'hermiq') to point the companion at another backend.

Provided values​

CnAppRoot calls provide() with the following keys; descendants inject these:

Inject keyProvided value
cnManifestThe manifest prop
cnCustomComponentsThe customComponents prop
cnTranslateThe translate prop
cnPageTypesThe pageTypes prop
cnOpenUserSettingsFunction that opens the hosted NcAppSettingsDialog. CnAppNav binds this to manifest entries with action: "user-settings"; consumer apps can also invoke it directly via inject for custom triggers (e.g. an avatar-menu entry).
cnAppIdThe consuming app's slug (mirrors the appId prop, e.g. "pipelinq"). Read by CnWidgetWrapper's built-in Request a feature default to pre-fill CnSuggestFeatureModal's app prop — apps don't have to wire it per-widget.
cnFeatureRequestRepoTarget repo slug for the in-product feature-request deep link (e.g. "Conduction/pipelinq"). Read from manifest.nav.featureRequestRepo when set; otherwise falls back to Conduction/<appId> (the convention for every Conduction app on Codeberg). Used by CnWidgetWrapper's built-in Request a feature default.
cnFeatureRequestForgeForge config { type, baseUrl } for the feature-request deep link. Read from manifest.nav.forge (merged over the Codeberg default). Switching the fleet's forge — back to GitHub, or onto a self-hosted Forgejo/Gitea — is just this one manifest field. Consumed by CnActionsMenu / CnSuggestFeatureModal.
cnMenuCountsReactive { [register]: { [schema]: number } } map of useObjectStore totals. Populated at mount for every menu[].count: "auto" entry whose resolved page is type: "index" with register + schema in its config. Read by CnAppNav inside resolveCount() to render NcCounterBubble badges. One ?_limit=1 fetch per unique (register, schema) pair; failures degrade silently to "no badge" so a broken endpoint never blanks the navigation.
cnDataSourcesThe dataSources prop, as passed. A plain value captured once — kept for backwards compatibility; prefer cnDataSourcesState below.
cnDataSourcesStateLive data-source holder: { value, loading, error, hasLoader }, where value is the { registers: [...] } payload. Provided by reference and mutated in place — its identity never changes, which is what lets the one-shot provide() see every update. Descendants resolve cnDataSourcesState.value ?? cnDataSources, so a host passing only the legacy snapshot still works.
cnRefreshDataSourcesasync () => void — re-runs dataSourcesLoader and updates the holder. Called by the pages-editor modals on open; a no-op when no loader is configured. Concurrent calls share one in-flight fetch, and a failure keeps the last good list while recording error.

Slots​

SlotScopeDefaultDescription
(default)——Page content area inside NcAppContent. In real apps, pass <router-view /> here.
loading—<CnAppLoading />Shown during the loading phase
dependency-missing{ dependencies }<CnDependencyMissing :dependencies />Shown when any dependency is missing or disabled
or-missing{ missingApps }Default <NcEmptyContent> linking to the OpenRegister app-store integration pageShown when any app in requiresApps is missing per the OCS capabilities check. Override to fully replace the empty state.
setup{ steps, status }<CnSetupWizard :cancellable="false" />Replaces the gating first-time-setup surface (a required manifest.setup step is unmet). steps is manifest.setup.steps; status is the useSetupStatus state. Does not affect the non-gating overlay — see First-time setup.
menu—<CnAppNav :permissions />Replaces the default app navigation
header-actions——Mounted inside NcAppContent, alongside the default slot
sidebar—The resolved cnPageSidebarComponent when set, otherwise emptyMounted next to NcAppContent (e.g. for NcAppSidebar). Gated by the cnPageSidebarVisible inject — when a descendant CnPageRenderer flips it to false (because the current manifest page declares sidebar.show: false), this slot stops rendering. The default (no provider) is value-true so the slot keeps rendering. The slot's default content is driven by the cnPageSidebarComponent inject — when the current page declares a sidebarComponent registry name, the resolved component renders here unless the consumer supplies a #sidebar slot override (override wins). See Per-page sidebar visibility and Per-page sidebar component.
footer——Mounted inside NcAppContent, after the default slot
user-settings-sections——The app's own NcAppSettingsSection children, ADDED to the library's default sections (notifications, credentials, walkthrough replay, integrations). Place, order or hide the defaults with userSettingsSections.
user-settings——The older slot: the app's own NcAppSettingsSection children, REPLACING the default sections. Filling it draws only this content and the integrations section, unless userSettingsSections names more. Prefer user-settings-sections.

User-settings modal​

CnAppRoot always mounts a single NcAppSettingsDialog and exposes a cnOpenUserSettings provide-injected method any descendant can call to open it. The default trigger is CnAppNav — manifest entries declaring action: "user-settings" are wired to this method automatically.

The modal draws five kinds of section, in this order by default:

KeySectionDrawn when
appThe app's own sections, from #user-settings-sections (and the older #user-settings)the app fills a slot
notificationsThe notification-preferences pane (CnNotificationPreferences)always
credentialsThe personal credential broker (CnCredentials)always
walkthroughA Walkthrough section with a Restart walkthrough button (ADR-043): it closes the dialog and re-fires the tour from step 1the manifest declares an enabled walkthrough with at least one tour
integrationsThe links that leave this app for another one (ADR-110)the manifest declares section: "integrations" menu entries

An app adds its own sections through #user-settings-sections and keeps every default:

<CnAppRoot :manifest="manifest" app-id="decidesk">
<template #user-settings-sections>
<NcAppSettingsSection id="general" :name="t('decidesk', 'General')">
<p>{{ t('decidesk', 'Personal preferences for Decidiq.') }}</p>
</NcAppSettingsSection>
</template>
</CnAppRoot>

To place, order or hide the defaults, pass userSettingsSections. A board that draws the app's sections, then credentials and the walkthrough, and no notifications pane or integrations:

<CnAppRoot :manifest="manifest" app-id="decidesk"
:user-settings-sections="['app', 'credentials', 'walkthrough']">
<template #user-settings-sections>
<!-- the app's own NcAppSettingsSection children -->
</template>
</CnAppRoot>

The older #user-settings slot keeps what it always did: it replaces the defaults, so only its content and the integrations section are drawn. An app on that slot that draws credentials or the walkthrough by hand can drop its copies and pass userSettingsSections (for example ['app', 'credentials', 'walkthrough']), or move to #user-settings-sections.

The dialog's title and the names of the sections the library draws come from the library catalogue first ("Persoonlijke instellingen", "Inloggegevens", "Rondleiding" in Dutch), then from the app's translate.

Hoisted index sidebar​

CnAppRoot provides a reactive holder, cnIndexSidebarConfig, that descendants — specifically CnIndexPage — write to in order to mount their embedded CnIndexSidebar at NcContent level. NcAppSidebar must be a direct child of NcContent to render as the proper right-side overlay; nested anywhere deeper it falls back to in-flow layout, which is why the lib hoists.

The hoist is automatic — apps using CnAppRoot get correct positioning the moment they pass a sidebar: { enabled: true } config on a type: 'index' manifest page. No consumer template changes required. The hoisted sidebar mounts as a sibling of the consumer's #sidebar slot, so existing #sidebar content (e.g. CnObjectSidebar for detail pages) keeps working unchanged.

Apps mounting CnIndexPage standalone (without CnAppRoot) keep the legacy inline rendering — the cnHostsIndexSidebar sentinel defaults to false in that case, so CnIndexPage renders the sidebar in-tree as before.

Hoisted object sidebar (detail pages)​

CnAppRoot also provides an objectSidebarState holder that CnDetailPage writes into via syncSidebarState() — { active, objectType, objectId, register, schema, title, subtitle, tabs, hiddenTabs, ... }. When a detail page is active and provides an objectType + objectId, CnAppRoot auto-mounts CnObjectSidebar at NcContent level with those props. ADR-017 again: NcAppSidebar must be a direct child of NcContent to position correctly.

The auto-mount defers when:

  • the consumer supplies a #sidebar slot (their slot keeps owning the rail);
  • an ancestor already provides objectSidebarState (the ancestor renders its own sidebar — e.g. decidesk's host wrapper); or
  • objectType + objectId are empty (defense-in-depth against CnIndexPage's inject('sidebarState') ?? inject('objectSidebarState') fallback writing active: true into the wrong channel).

CnAppRoot also exposes a dedicated sidebarState holder for the index-sidebar channel. The two reactive holders are distinct references so index-page writes never leak into the object-sidebar auto-mount (the openbuilt double-sidebar regression).

Mounting virtual apps with an in-memory manifest​

Most CnAppRoot consumers ship a static manifest.json and let useAppManifest('myapp', bundled) fetch the optional /index.php/apps/myapp/api/manifest override. Some consumers — notably the OpenBuilt app builder — render virtual apps whose manifest is constructed in memory at runtime, with no static file and no backend route.

For those hosts, useAppManifest now exposes a direct in-memory overload that mounts the manifest synchronously without any HTTP IO:

import { CnAppRoot, useAppManifest } from '@conduction/nextcloud-vue'

setup() {
const builderManifest = buildManifestFromStore()
const { manifest, isLoading } = useAppManifest({ manifest: builderManifest })
return { manifest, isLoading }
}

The composable returns the same { manifest, isLoading, validationErrors, unresolvedSentinels } shape as the legacy positional signature, so CnAppRoot consumes it unchanged. isLoading.value is false immediately because no fetch is queued. See useAppManifest — Mounting an in-memory manifest for the full overload contract and the optional validate: true flag.

Historical workaround​

Before this overload existed, virtual-app hosts had to fake an HTTP fetch by passing a stub options.endpoint and an options.fetcher that resolved synchronously to the in-memory manifest. That workaround is documented in the OpenBuilt bootstrap-openbuilt change (Decision 4) and is now historical — the in-memory overload is the supported path. The legacy options.endpoint / options.fetcher parameters remain fully supported for their intended uses (tests, alternative-host deployments).

Board look​

An app opts in to the look of the screens on identity.conduction.nl with one key. An app without it renders exactly as before.

{ "look": "board", "pages": [ { "id": "settings", "type": "settings", "config": { "look": "nextcloud" } } ] }
  • look at the manifest root is "nextcloud" (the default) or "board". The look prop of CnAppRoot wins over it.
  • In the board look CnAppRoot puts the class cn-look-board on its root element. A page with its own config.look that differs puts cn-look-board or cn-look-nextcloud on its own root, and the nearest class wins.
  • src/css/look-board.css defines the board dimensions as --cn-board-* custom properties on .cn-look-board: --cn-board-content-padding, --cn-board-content-max-width, --cn-board-section-gap, --cn-board-control-height, --cn-board-control-radius, --cn-board-card-radius, --cn-board-card-padding, --cn-board-hairline and --cn-board-text-soft. Colours stay Nextcloud variables.
  • CnAppRoot provides the resolved look as cnLook, and a page with config.look re-provides its own to its descendants. Components read it with useLook(props), which returns look, isBoard and lookClass. A look prop on the component overrides the injected value.
  • A dialog is teleported to document.body, outside CnAppRoot, so a .cn-look-board rule cannot reach it. Bind lookClass on the dialog's own container.
import { useLook } from '@conduction/nextcloud-vue'

export default {
props: { look: { type: String, default: '' } },
setup(props) {
const { isBoard, lookClass } = useLook(props)
return { isBoard, lookClass } // <div :class="lookClass"> on the teleported container
},
}

The brand block in Nextcloud's header​

Under the board look, an app that declares a brand (nav.brand, or the brand prop) gets a 237px block at the start of Nextcloud's own header (#header), before the app menu: the emblem, the organisation (caption) above the app name (name), and a 1px divider at its end. The block exists without CnAppNav, so an app with its own menu has it too. CnAppNav stops drawing the block while the header does (cnBrandInHeader). Set nav.brand.placement: "nav" to keep the block in the navigation.

Nextcloud offers no extension point for apps in #header, so this is unsupported by Nextcloud and may break on an update. The library limits the damage: it adds one node of its own and never moves, edits or removes a node Nextcloud drew, puts that node back if Nextcloud re-renders the header, and falls back to the navigation when #header is absent. Sizes: --cn-board-brand-width (237px), --cn-nav-emblem-size (34px).

Support dialog​

PropTypeDefaultDescription
supportDialogBoolean | ObjecttrueAuto-mount the built-in support/feedback dialog. Pass false to disable, or an options object to configure it.

AI companion​

PropTypeDefaultDescription
aiCompanion (ai-companion)BooleanfalseOpt-in floating AI-chat companion (CnAiCompanion). Off by default; pass true to mount it. When enabled it still self-gates on its own backend health probe and hides on chat pages. The companion is an AI capability provided by the Hermiq app — apps opt in explicitly rather than every app auto-mounting it whenever a chat backend is reachable.
commandPalette (command-palette)Boolean | ObjectfalseOpt-in Ctrl/Cmd+K command palette (CnCommandPalette, see its own doc page). Off by default; pass true for zero-config navigation + registered actions, or an object to override any CnCommandPalette prop (most commonly { objectSearch: createObjectSearchSource({...}) } to wire live OpenRegister search).

Scoped theming (runtime.theme)​

CnAppRoot's root <NcContent> always carries data-nldesign-theme-scope="<appId>" (inert when no theme is applied — an unused data-* attribute costs nothing). When the effective manifest declares runtime.theme — { source: "nldesign", tokenSet, tokenSetName?, preview? }, validated by $defs/runtimeTheme in app-manifest-v2.schema.json — CnAppRoot calls useScopedTheme().apply(effectiveManifest, appId) automatically, no per-app code required:

{ "runtime": { "theme": { "source": "nldesign", "tokenSet": "gemeente-blauw" } } }
  • Re-applies whenever the effective manifest's runtime.theme changes — including an in-app manifest-editor (ADR-041) live-preview edit — via a deep, immediate watcher over the same editing-vs-props.manifest branch the cnManifest provide getter uses.
  • Tears the scoped style down on beforeDestroy().
  • A manifest that declares no runtime.theme renders identically to before — no style element, no behaviour change. nldesign absent, unreachable, or serving non-conformant token CSS degrades silently to default styling (at most a console.warn), never a throw and never a blocked shell.

CnPageRenderer needs no change — the scope lives at this container level (one managed <style> per app instance), so CSS custom properties cascade to every page automatically.

Deprecated: in-app soft-dependency banners​

softDependencyNotices (Boolean, default false) restores the orange notices that used to render above every routed page, one per unresolved optional dependency.

They are off by default because they stacked: an app declaring four optional leaves showed four cards above its own content and pushed the page below the fold, on every load, for an audience who cannot act on them. Mount CnLeafDependencySettings in the app's admin settings instead — it carries the same two states and the same install/enable action.

unresolvedSoftDependencies is unchanged and still exposed, so an app rendering its own surface from it keeps working. The prop is a bridge for one release and is slated for removal.

Hiding the navigation (hideMenu)​

PropTypeDefaultDescription
hideMenuBooleanfalseRender no app navigation at all: neither the default CnAppNav nor the #menu slot, so the content starts at the left edge. An empty #menu override cannot do this (an empty slot falls back to the default CnAppNav), which is why launchpad passed a hidden empty span.

CnAppRoot also provides cnMenuItemCounts, the filtered totals for menu entries whose count is { register, schema, filter } (see CnAppNav).

User settings in the board look​

Under the board look (look: "board" or manifest look) the user settings open in the board dialog (board PqPersoonlijk) instead of NcAppSettingsDialog: an eyebrow, the title and a subtitle, a 200px navigation listing every section with its icon, the sections, and a footer "Changes are saved straight away · Pipelinq" (the app's name) with Close. The sections stay the app's: every NcAppSettingsSection in #user-settings-sections registers itself with the board dialog as it does with NcAppSettingsDialog, so give each one an #icon slot to show an icon in the navigation. The library's own sections carry one. The Nextcloud look is unchanged.

Nextcloud does not expose its personal settings sections to an app's page, so the board's list of Nextcloud's own settings (Persoonlijke info, Beveiliging, ..., Privacy) is configured with userSettingsNextcloudLinks. With it, the navigation lists those links first and then one entry named after the app, with the app's sections under it (board DqPersoonlijkeInstellingen). A section's #icon also stands before its heading in the board dialog. The board dialog shows one section at a time: picking a navigation entry shows that section and moves focus to its heading; the other sections stay mounted but hidden, so what was typed in them survives a switch.

const userSettingsNextcloudLinks = [
{ label: 'Personal info', section: 'personal-info', icon: 'AccountOutline' },
{ label: 'Security', section: 'security', icon: 'LockOutline' },
{ label: 'Privacy', section: 'privacy', icon: 'ShieldAccountOutline' },
]