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
| Phase | When | Default rendering | Override slot |
|---|---|---|---|
loading | While isLoading is true | <CnAppLoading /> | #loading |
dependency-missing | After loading; an unresolved HARD dependency in manifest.dependencies | <CnDependencyMissing /> | #dependency-missing |
setup | HARD dependencies satisfied; a required manifest.setup step is unmet | <CnSetupWizard :cancellable="false" /> | #setup |
shell | Manifest 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.
| Path | Condition | Behaviour |
|---|---|---|
| Gating | A required step is unmet | The 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-gating | Every required step is met, but at least one actionable optional step isn't | The 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
Nextis 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
@completethe overlay stays mounted soCnSetupWizard's result phase ("Setup complete.") is visible; its Close button drives the unmount.