Plugins and modules

A plugin is metadata plus a set of modules, and a PLEX app is the plugins it loads.

Model

A plugin’s metadata names it: a key that no other plugin uses, a display name, a description and an icon. Its modules do the work. Each module activates on an event, runs once, and contributes capabilities: typed values, such as a surface component or an operation handler, that other modules look up.

Plugin.define takes the metadata, Plugin.addModule adds each module, and Plugin.make returns a function that the app’s plugin manager calls to create the plugin.

import * as Plugin from '@dxos/app-framework/Plugin';

export const HelloPlugin = Plugin.define(meta).pipe(
  Plugin.addModule(GreetingModule),
  Plugin.make,
);

A plugin you publish describes itself in a dx.config.ts manifest instead. Plugin.config takes the same metadata, plus registry fields such as tags, and the list of modules. It returns the plugin’s meta and its make function, so the registry can read the plugin without loading its code.

dx.config.ts

import * as Plugin from '@dxos/app-framework/Plugin';
import * as AppCapability from '@dxos/app-toolkit/AppCapability';
import * as AppSurface from '@dxos/app-toolkit/AppSurface';
import * as SpaceCapability from '@dxos/plugin-space/SpaceCapability';

import { StashNamespace } from './src/namespace.ts';

const config: Plugin.PluginConfig = Plugin.config({
  plugin: {
    key: StashNamespace.key,
    name: 'Stash',
    author: 'Example',
    description:
      'A reading list: save links with a note, and mark them as read.',
    icon: { key: 'ph--tray-arrow-down--regular', hue: 'indigo' },
    tags: ['labs'],
  },
  modules: [
    AppCapability.translations(
      () => import('./src/translations.ts', { with: { type: 'module-url' } }),
    ),
    AppCapability.schema(
      () =>
        import('./src/capabilities/schema.ts', {
          with: { type: 'module-url' },
        }),
    ),
    AppCapability.operationHandler(
      () =>
        import('./src/capabilities/operation-handler.ts', {
          with: { type: 'module-url' },
        }),
    ),
    SpaceCapability.createObject(
      () =>
        import('./src/capabilities/create-object.ts', {
          with: { type: 'module-url' },
        }),
    ),
    AppCapability.appGraphBuilder(
      () =>
        import('./src/capabilities/app-graph-builder.ts', {
          with: { type: 'module-url' },
        }),
    ),
    AppCapability.surface(
      () =>
        import('./src/capabilities/react-surface.ts', {
          with: { type: 'module-url' },
        }),
      {
        roles: [AppSurface.Article],
      },
    ),
    AppCapability.skillDefinition(
      () =>
        import('./src/capabilities/skill-definition.ts', {
          with: { type: 'module-url' },
        }),
    ),
  ],
});

export const { meta, make } = config;

export default config;

The Stash plugin from the learning path has seven modules. Each waits on an event and contributes one capability. Five of them:

Behavior

• A module is inline or lazy. Capability.inlineModule carries its body with it. Capability.lazyModule names a loader, and the plugin manager imports the body only when the module’s event fires. A module whose event never fires never loads, so a plugin costs nothing until it is used.

import * as Effect from 'effect/Effect';
import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
import * as Capability from '@dxos/app-framework/Capability';

// The module body loads only when its event fires. The loader's default export
// is checked against `provides`.
const LazyGreetingModule = Capability.lazyModule(
  'LazyGreeting',
  { provides: [Greeting], activatesOn: ActivationEvents.Idle },
  async () => ({
    default: Capability.makeModule(() =>
      Effect.succeed(Capability.contribute(Greeting, 'Hello, later')),
    ),
  }),
);

• The module makers in AppCapability, such as AppCapability.surface, fix a module’s capability and its event, so a manifest names only the file to load. The loader’s default export is checked against the capability at compile time.
• Every module declares what it provides and what it requires. The plugin manager uses them to order activation; Activation covers the rules.
• Plugins never import each other’s modules. A plugin that extends another contributes to a capability the other reads.

Limits

• A plugin’s key is a reverse-domain name, and its last segment must be camelCase. Keep the key once the plugin has users: settings and enabled state are stored under it.
• A module keeps no state between activations. What it needs to keep, it contributes or stores.