Boot sequence

When Nuxt loads @owdproject/core, the engine runs roughly this sequence:

1. Resolve config path — desktop.config.ts, or legacy owd.config.ts, from the desktop rootDir.
2. Validate — theme, apps, modules shapes; warn on keys that look like Nuxt options (not on extension keys such as fs / terminal).
3. Merge full config — entire desktop.config.ts export → runtimeConfig.public.desktop (+ coreVersion); same reference on appConfig.desktop. Never spread onto _nuxt.options.
4. Install Pinia — required before theme/modules/apps that use stores or defineDesktopApp queues.
5. installDesktopPackage in order:
   • theme
   • each entry in modules
   • each entry in apps
6. Shared stack — Nuxt Fonts, Nuxt Icon, Pinia, VueUse, i18n, etc. (as configured by core).
7. Register globals — Core components (DesktopCore, DesktopWindow, etc.), composables, stores; client plugins (resize, app registration flush).

If step 1–2 fails, bootstrap stops (fail-fast).

Theme module hook

When the theme’s setup runs, core has already written user shell config. The theme typically:

import { defu } from 'defu'

nuxt.options.runtimeConfig.public.desktop = defu(
  nuxt.options.runtimeConfig.public.desktop ?? {},
  options, // module defaults
)

User values win; theme defaults fill gaps.

Conditional explorer

Themes often gate extra installs:

if (nuxt.options.modules.includes('@owdproject/module-fs')) {
  await installModule('@owdproject/kit-explorer')
  // theme explorer plugins / components
}

More detail: Kernel contract · Architecture overview.