Skip to content

UI5 source resolution — the SDK as a multi-app package ​

laravelui5/sdk ships several UI5 apps from one Composer package (Partners, Settings, Launchpad). This is the SDK's standing exception to the one-app-per-package shape that Core, Auth, and the host apps use. It rides on a Core convention (the standard PackageStrategy), so the SDK adds no resolver of its own — each app looks exactly like a single-app package, just foldered as a sibling under the ui5/ umbrella.

The umbrella layout ​

The package root is the ui5/ umbrella (see ui5/README.md). The framework lives in ui5/Sdk/; each app is its own sibling folder with its own sub-namespace under LaravelUi5\Sdk\, and — the key point — its own resources/ui5:

ui5/
  Sdk/                              # framework (provider, migrations, routes, shared assets)
    src/                            # LaravelUi5\Sdk\
    resources/{views,assets,stubs,taxonomy}   # cross-app framework resources (NOT app frontends)
  Partners/                         # an app
    src/PartnersModule.php          # LaravelUi5\Sdk\Partners\PartnersModule
    resources/ui5/                  # ← this app's frontend artifacts, resolved here
      Component-preload.js
      manifest.json
      i18n/{i18n,i18n_de,i18n_en}.properties
  Settings/   … src/ + resources/ui5/
  Launchpad/  … src/ + resources/ui5/

ui5/composer.json maps each namespace by longest PSR-4 prefix (LaravelUi5\Sdk\Partners\ → Partners/src/, etc.), so an app folder is a self-contained unit: source in src/, help in doc/, frontend in resources/ui5/.

How Core resolves a module's UI5 source ​

Core's Ui5SourceStrategyResolver picks a source strategy for each registered module, in order:

  1. .ui5-sources.php workspace override → WorkspaceStrategy (the dev live-reload path — see below)
  2. resources/app (sibling of src/) → SelfContainedStrategy
  3. resources/ui5 (sibling of src/) → PackageStrategy (where each SDK app resolves)
  4. multi-app ../../resources/ui5-<slug> → SelfContainedStrategy (legacy fallback for the retired in-Sdk/src layout; no SDK app uses it)

For PartnersModule at Partners/src/PartnersModule.php, moduleDir is Partners/src, so check 3 resolves Partners/src/../resources/ui5 = Partners/resources/ui5 and stops there. Each app resolves to its own folder because the strategy anchors on the module class file's directory.

Why not the multi-app fallback (check 4)? The apps used to live insideui5/Sdk/src/<App>/, and their built assets in ui5/Sdk/resources/ui5-<slug>; check 4 (src/<App>/../../resources/ui5-<slug>) resolved that. When the apps moved out to sibling ui5/<App>/ folders (so the Core generators scaffold into their expected ui5/<App>/src/ home — see ui5/README.md), the resources moved with them into the standard resources/ui5 shape. Check 4 is now dead for the SDK; the plain single-app PackageStrategy carries every app.

If none match, the resolver throws and the whole registry fails to load — so every registered module must resolve to a real source folder.

Required files in each app folder ​

resources/ui5/ must contain — exactly these — for both source resolution and ability introspection to succeed:

  • Component-preload.js
  • manifest.json
  • i18n/i18n.properties (+ any per-locale i18n_*.properties)

At ui5:sync, ManifestAbilityExtractor reads manifest.json andi18n/i18n.properties for the app; a missing file fails the registry load loudly (no partial sync). These artifacts are committed with the package and ship in the subsplit, so packaged resolution works identically in CI and a customer install.

The dev workflow — ui5:refresh ​

The artifacts above are produced from the workspace UI5 project by the host-side development command (app/Commands/Ui5RefreshCommand.php, SDK-development-only):

php artisan ui5:refresh partners   # build ../ui5-partners, copy dist → ui5/Partners/resources/ui5
php artisan ui5:refresh            # every implemented target

It is a pure build-and-copy step — it never touches the registry, so it can always (re)create a missing resources/ui5 folder. The slug studly-cases to the app folder (partners → Partners). It copies only the files listed above and fails loud if the source, the dist/, or a required artifact is missing. Declared-but-unimplemented targets throw on an explicit call and are skipped by the catch-all run.

Run ui5:refresh (all targets) before ui5:sync: refresh populates the resources/ui5 folders that sync's registry load depends on.

.ui5-sources.php — the dev live-reload override ​

In this dev host, .ui5-sources.php maps each app module to its workspace frontend project (../ui5-partners/, ../ui5-settings/, ../ui5-launchpad/). When present, check 1 wins and the app is served live from the workspace webapp/ — edit-and-reload, no ui5:refresh round-trip. Delete or comment the override to serve from the committed resources/ui5 instead (the same path a packaged install takes); this is the way to smoke-test packaged resolution locally.

Adding a new SDK app ​

  1. Create ui5/<App>/src/<App>Module.php (+ App/Manifest) under LaravelUi5\Sdk\<App>, and add the PSR-4 mapping to ui5/composer.json (and to the development host's mirror of it).
  2. Register it in SdkServiceProvider::boot() (->add(<App>Module::class)).
  3. Add the target to the host ui5:refresh command (slug => [source, kind, implemented]).
  4. ui5:refresh <slug> to bake ui5/<App>/resources/ui5, then ui5:sync.