Skip to main content

@uxland/harmonix

npm

The core of Harmonix. It defines the contract between a shell and its plugins (Plugin, HarmonixApi and the related types), loads the plugins (bootstrapPlugins) and provides the region manager that shells use to create regions and register views. It does not render anything and has no shell of its own: each application builds one on top of it. Plugins usually only import its types.

Install​

npm install @uxland/harmonix @uxland/regions lit

@uxland/regions (^1.0.0) is a dependency of the core. A shell also imports it directly, for the @region decorator and the region adapters. createRegionHost returns a mixin for Lit elements, so a shell built with it needs lit.

Main exports​

Loading plugins​

ExportDescription
bootstrapPlugins(plugins, apiFactory)Imports and initializes the plugins in parallel. Calls apiFactory once per plugin and then plugin.initialize(api). Returns one BootstrappedPlugin per plugin. A plugin that fails is logged to the console and does not stop the others. Throws if the list is empty.
PluginDefinition{ pluginId, importer }. importer() returns a promise of the plugin module.
Plugin<TApi>What a plugin module exports: initialize(api) and dispose(api), both async.
BootstrappedPlugin<TApi>{ dispose(), importedPlugin, apiInstance }.
ApiFactory<TApi>(info: PluginInfo) => TApi: builds the API for one plugin.
import { bootstrapPlugins, type ApiFactory, type HarmonixApi } from "@uxland/harmonix";

const apiFactory: ApiFactory<HarmonixApi> = (pluginInfo) => ({
  pluginInfo,
  regionManager: createRegionManagerProxy(pluginInfo), // your shell's implementation
  createLocaleManager, // your shell's implementation
});

const plugins = await bootstrapPlugins(
  [{ pluginId: "my-plugin", importer: () => import("https://example.com/plugins/my-plugin.js") }],
  apiFactory,
);

Regions​

ExportDescription
createRegionManager(name)Creates the shell's region manager (a RegionManager).
createRegionHost(regionManager)Returns the Lit mixin that elements declaring regions with @region must extend.
RegionManager / IRegionManageradd, getRegion, remove, registerViewWithRegion, unregisterViewFromRegion, getRegisteredViews, clear, destroy and createRegionManager.

API types​

ExportDescription
HarmonixApiThe minimum API a plugin receives: pluginInfo, regionManager and createLocaleManager(messages). Shells extend it.
HarmonixRegionManagerThe region manager as plugins see it: registerView, removeView, activateView, deactivateView, getRegion, isViewActive, containsView.
HarmonixViewDefinition{ id, factory, sortHint?, isDefault?, removeFromDomWhenDeactivated? }. factory returns a promise of an HTMLElement.
HarmonixLocaleApi, LocalizationMessages, TranslationsTranslations for a plugin: translate(path, variables?), getCurrentLanguage(), getTranslations().
HarmonixBroker, BrokerDisposableHandler, IEvent, IRequestThe broker interface: send, registerRequest, publish, subscribe. The core only defines it; each shell implements it.
PluginInfo{ pluginId }.

The full reference is in API reference, Regions and views and Broker.

Versions​

The demo shell depends on ^1.1.6.