ADR 0021: The frontend of ee/ is a separate plugin package¶
- Status: Accepted (2026-11-16)
- Date: 2026-11-16
- Issue: #307, part of #292
- Builds on: ADR 0017, ADR 0020
Context¶
ADR 0017 keeps the Go code of ee/ out of the core: the core never imports
it, it is wired only in the composition root behind the build tag ee, and a
build without the tag is MIT only. It says nothing about the frontend. The
ee/ features (licence keys, announcements, absences, branding, team tabs)
all have screens, so the web app needs the same separation. People should
also see in the settings which features for organisations exist, including
the ones that are switched off.
Decision¶
A plugin package with its own build¶
- The frontend of
ee/is its own package inee/web/with its ownpackage.jsonand Vite build. It produces one ES module,plugin.js, plus its lazy chunks. - The core web app (
web/) never imports fromee/web/. The package may import types and plain helpers from the core's plugin API (web/src/app/plugins/), nothing else. - The plugin bundles its own Svelte runtime. Its screens do not become part of the core's component tree: the core hands each one a host element and the plugin mounts into it and unmounts on request. This keeps the two builds independent of each other's compiler and runtime versions.
The plugin API (core, MIT)¶
- A plugin exports
plugin: WaylightPluginwith widgets, settings sections and search contributions. Each entry carries its metadata (kind, title, category, icon, default size, the licence feature it needs) and amount(host, context)function that returns anunmountfunction. - The context gives the plugin what core features get from the container: the API client (session and CSRF handled), the active language, the signed in account and its role, and a way to ask the core to reload.
- The core wraps plugin entries into its normal widget, settings and search
registration, so the picker, the settings dialog and the search field show
them without knowing about
ee/. - Search contributions are commands (
searchActions, #453): keywords, a title and arun(context). The core matches the typed text against the keywords and lists the action under Actions. Guests get none, and an action whose feature is not fully licensed is left out, since it could only fail. - The contract grows by optional fields only.
apiVersionchanges only for a breaking change, which the loader then refuses; a plugin built against an older contract keeps loading, and an older core ignores fields it does not know.
Loading¶
GET /api/plugins(core) lists the plugin bundles the server offers. A build without the tageeoffers none, and the app loads nothing.- A build with the tag
eeembedsee/web/distand serves it under/ee/.GET /api/pluginsthen lists/ee/plugin.js, and the app loads it with a dynamicimport()after sign-in. - Releases and images stay built without the tag until the licence files are final (#319).
Features that are switched off stay visible¶
- The plugin always registers all of its features. Widgets of a feature
without a licence are left out of the widget picker, as the server leaves
the module out of
GET /api/modulesand answers its endpoints with 403. - Settings sections are listed even then. A section whose feature is off
shows what the feature does and that it needs a licence key, instead of
its form. One section, Features for organisations, lists every feature
with its state (on, read only, off) from
GET /api/licence/featuresand takes the licence key.
Tests and checks¶
- The plugin package has its own Vitest run in CI, next to the core's.
- An architecture test fails if a file under
web/imports fromee/. make build-eebuilds the plugin and the server with-tags ee; CI runs it, and an end-to-end test loads the plugin with a test licence key.
Consequences¶
- The MIT bundle does not grow with
ee/features; the plugin is downloaded only from servers that offer it. - A second Svelte runtime is loaded with the plugin, about 20 KB gzipped.
- Plugin screens cannot use core components directly; shared look comes from the core's CSS variables, which apply inside the host element.
- The plugin API becomes an interface the core keeps stable for
ee/.
Alternatives considered¶
ee/frontend insideweb/src/features/: simplest, but it puts code under another licence into the MIT tree and into every bundle.ee/web/compiled into the core bundle behind a build flag: one build with two variants, but the core build would depend onee/sources.- Sharing the core's Svelte runtime through an import map: smaller, but ties the plugin to the exact runtime build of the core.