Plugin Interface

A TypeScript library for plugin management, built with React, TypeScript, and Vite.

Automatic Releases

Releases are automatically created when code is merged to main using semantic-release. Use conventional commit messages to trigger version bumps.

Commit Types

| Commit Type | Version Bump | Example | | ----------- | ------------ | ----------------------------- | | fix: | Patch | fix: resolve memory leak | | feat: | Minor | feat: add plugin validation | | feat!: | Major | feat!: refactor plugin API |

Other types (docs:, test:, chore:, etc.) do not trigger releases.

Version Examples

| Current | Commit Type | New Version | | ------- | ----------- | ----------- | | 0.0.1 | fix: | 0.0.2 | | 0.0.1 | feat: | 0.1.0 | | 0.1.0 | feat!: | 1.0.0 |

Process

1. Commit with conventional message (fix:, feat:, etc.)
2. Merge to main branch
3. CI/CD runs tests → builds → publishes (if tests pass)

Note: Only commits on main trigger releases. Multiple commits use the highest version bump type.

Plugin Generator

Generate a new plugin project from a template using an interactive prompt system or command-line arguments.

Quick Start

Using npx (recommended - no installation needed):

npx @opengeoweb/plugin-interface

Or install globally:

npm install -g @opengeoweb/plugin-interface
create-plugin

Interactive Mode (Recommended)

When you run create-plugin without arguments, you'll be prompted for all options:

npx @opengeoweb/plugin-interface

The interactive prompts will ask for:

• Plugin name: Name of your plugin (e.g., MyAwesomePlugin)
• Scopes: Multi-select interface to choose from available scopes:
  • time - Time state management (setTime events)
  • animation - Animation time span management (start/end times)
  • features - Map features management (addLayer, removeLayer, setLayerFeatures)
  • featureSelection - Selected feature ids within feature layers (setSelectedFeatures)
  • applicationConfiguration - Read-only GeoWeb application configuration (host-pushed)
  • notification - Send notifications with different severities to GeoWeb
  • user - Read-only user authentication and profile information (host-pushed)
  • authentication - Read-only authentication tokens and credentials (host-pushed)
• Initial version: Defaults to 1.0.0
• Output directory: Defaults to current directory
• Package name: Optional, defaults to @your-org/<kebab-name>

Non-Interactive Mode

You can also provide all options via command-line arguments:

npx @opengeoweb/plugin-interface MyPlugin \
  --scopes time,animation \
  --version 1.0.0 \
  --output-dir ./ \
  --package-name @myorg/my-plugin

Command-Line Options

• <plugin-name> (required in non-interactive mode): Name of your plugin
• --scopes <scope1,scope2>: Comma-separated list of scopes (default: time)
• --version <version>: Initial version (default: 1.0.0)
• --output-dir <dir>: Output directory (default: current directory)
• --package-name <name>: Package name (default: @your-org/<kebab-name>)

What Gets Generated

The generator creates a complete plugin project with:

• ✅ React component structure with scope integration
• ✅ TypeScript configuration
• ✅ Vite build configs
• ✅ Storybook setup for development and testing
• ✅ Default scope functionality (state subscriptions, event handlers, controls)
• ✅ Interactive demo story with scope controls
• ✅ Proper plugin interface integration
• ✅ Example event handlers and initialization code

Example Usage

Interactive mode:

npx @opengeoweb/plugin-interface
# Follow the prompts

Non-interactive mode:

npx @opengeoweb/plugin-interface WeatherWidget \
  --scopes time,animation \
  --version 0.1.0

After generation:

cd weather-widget
npm install
npm run storybook  # Start development server
npm run build:vite # Build for production

Available Scopes

• time: Manages time state with setTime events
• animation: Manages animation time spans with setAnimationStartTime, setAnimationEndTime, and setAnimationTimeSpan events
• features: Manages map feature layers (GeoJSON FeatureCollections with optional styling) with addLayer, removeLayer, and setLayerFeatures events
• featureSelection: Manages the selected feature ids within feature layers with setSelectedFeatures events. The state shape is { featureLayers: { id, selectedFeatureIds }[] }.
• applicationConfiguration: Read-only view of the GeoWeb runtime configuration (filtered, host-pushed). Plugins subscribe via onStateChange('applicationConfiguration', …) and cannot send events for this scope — the type system prevents sendEvent('applicationConfiguration', …). The host updates the value with pluginManager.setScopeState('applicationConfiguration', { geowebConfig: … }).
• notification: Sends notifications to the GeoWeb host with showNotification events. The host receives them via PluginManager.subscribeToState('notification', ...), where each event becomes the scope state.
• user: Read-only user authentication and profile information (host-pushed). Plugins subscribe via onStateChange('user', …) to access login state, user profile, and connection status. The host updates this via pluginManager.setScopeState('user', …).
• authentication: Read-only authentication tokens and low-level credentials (host-pushed). Plugins subscribe via onStateChange('authentication', …) to access token details for authorization decisions. The host updates this via pluginManager.setScopeState('authentication', …).

The generated plugin includes example code for all selected scopes, including state subscriptions, event handlers, and UI controls for testing.

Developing the Generator

If you're making changes to the generator templates or code, you need to rebuild the generator before testing:

Workflow

1. Make changes to templates in templates/plugin-template/ or generator code in src/generator/

2. Build the generator to compile your changes:

   npm run build

3. Run the generator locally (relative path works):

   node bin/create-plugin.js

4. Test the generated plugin:

   cd [new-plugin-folder]
   npm install
   npm run storybook  # Start Storybook to test your plugin

Testing local plugin-interface changes in a generated plugin

When you generate a plugin via node bin/create-plugin.js and want it to use your local plugin-interface code (instead of the published npm version), point its dependency to the local folder before installing:

1. In the generated plugin's package.json, change the dependency to:

   "@opengeoweb/plugin-interface": "file:.."

   (Adjust the path if your plugin lives somewhere else.)

2. From the plugin-interface repo root, build the library so the local dist/ is up to date:

   npm run build

3. Then in the generated plugin folder:

   npm install
   npm run storybook

Whenever you change plugin-interface, rerun npm run build in the root; the generated plugin will pick up the updated local build.

Quick Reference

# After making template changes
npm run build

# Generate a new plugin
node bin/create-plugin.js

# Test the generated plugin
cd [new-plugin-folder]
npm install
npm run storybook

Development

npm install          # Install dependencies
npm run dev          # Development server
npm test             # Run tests
npm run build    # Build library
npm run lint         # Lint code

How npm run build works

npm run build runs:

| Tool | Output | Consumer | | ------------------------- | -------------------------- | ---------------------------------------------------------- | | tsdown | dist/index.{js,cjs,d.ts} | Generated plugins importing @opengeoweb/plugin-interface | | tsc (build:generator) | dist/generator/*.js | The create-plugin CLI in bin/create-plugin.js |

tsdown's handling of package.json:

• peerDependencies left external.
• dependencies left external.
• devDependencies — bundled into dist/ (if anything in the runtime code path imports them).

Local Development with OpenGeoWeb

To test changes to the plugin-interface library directly inside OpenGeoWeb, you can use npm link for local development.

Why use npm link?

When developing plugins or working on the plugin-interface, you often need to:

• Test changes in a real OpenGeoWeb environment
• Iterate quickly on plugin behavior and APIs
• Avoid publishing a new package version for every small change

npm link allows you to use your local version of plugin-interface inside OpenGeoWeb, so you can immediately see the effect of your changes while developing plugins.

This makes it much faster to develop, debug, and validate plugin integrations.

Steps

1. Make changes in the plugin-interface repository

2. Build the library:

   npm run build

3. Link the package globally:

   npm link

4. Open the OpenGeoWeb project and link the package:

   npm link @opengeoweb/plugin-interface

5. Start OpenGeoWeb:

   nx serve

6. You should now see your local changes reflected in OpenGeoWeb.

Updating Changes

7. After making new changes in plugin-interface, rebuild:

   npm run build

No need to relink, OpenGeoWeb will pick up the updated build automatically.

Storybook

Storybook provides an interactive development environment for exploring and testing plugin integrations in isolation.

Running Storybook

npm run dev          # Start Storybook dev server (usually http://localhost:6006)

Available Stories

Located in the ./dev folder:

• PluginIntegration: Shows real-time interaction with plugin state (time, animation, lifecycle controls)

Benefits

• Isolated Development: Test components without running the full application
• Live Documentation: Interactive examples with editable props via Controls panel
• Visual Testing: See component states and variations side-by-side
• Accessibility: Built-in a11y addon helps catch accessibility issues early
• Rapid Prototyping: Quickly iterate on plugin behavior and UI integration

Stories include comprehensive documentation explaining the plugin architecture, custom hooks, and usage patterns.

Observing Plugin Events (subscribeToEvent)

PluginManager.subscribeToEvent(scope, callback) lets the host application observe plugin-originated events for a given scope. It is complementary to subscribeToState:

• subscribeToState(scope, cb) — fires whenever the scope's state changes (from either the host or a plugin). Use this to render the current state.
• subscribeToEvent(scope, cb) — fires only when a plugin dispatches an event for the scope.

Example

import { PluginManager } from 'plugin-interface';

const manager = new PluginManager();

const unsubscribe = manager.subscribeToEvent('features', (event) => {
  switch (event.type) {
    case 'addLayer':
      console.log('Plugin added a layer:', event.layer);
      break;
    case 'removeLayer':
      console.log('Plugin removed layer:', event.layerId);
      break;
    case 'setLayerFeatures':
      console.log(
        `Plugin updated features for ${event.layerId}:`,
        event.featureCollection,
      );
      break;
  }
});

// Later, when no longer interested:
unsubscribe();

The callback is fully typed against ScopeEventMap[scope], so the event union is narrowed per-scope.

Time Scope API

import {
  PluginManager,
  setTime,
  toIso8601Utc,
  assertIso8601Utc,
  type Iso8601Utc,
} from 'plugin-interface';

const manager = new PluginManager();
const instance =
  /* previously registered plugin instance with 'time' scope */ null as any;

// Basic: pass a valid UTC timestamp literal (compile-time shape checked)
setTime(instance, '2024-10-10T10:10:10Z');

// From Date: convert explicitly
const isoFromDate = toIso8601Utc(new Date());
setTime(instance, isoFromDate);

// Dynamic strings: setTime performs runtime validation and throws on invalid input
const raw = await fetchSomeTimestamp();
setTime(instance, raw);

// Optional pre-validation for clearer local error handling
try {
  const safe: Iso8601Utc = assertIso8601Utc(raw);
  setTime(instance, safe);
} catch (err) {
  console.error('Invalid time format', err);
}

// Explicit conversion example
const iso: Iso8601Utc = toIso8601Utc(new Date('2025-01-01T00:00:00.999Z'));
setTime(instance, iso);

Time Format & Validation

• Format: UTC ISO 8601 at seconds precision (YYYY-MM-DDTHH:MM:SSZ).
• Compile-time: template literal type Iso8601Utc validates only literal shapes.
• Runtime: setTime and helpers validate strings; errors include actionable hints (e.g., milliseconds present).

Helpers

• setTime(instance, iso): Dispatches the time scope setTime event if iso is valid.
• toIso8601Utc(date): Returns a compliant UTC string; removes milliseconds.
• assertIso8601Utc(str): Throws if str is not compliant; narrows type to Iso8601Utc when valid.

If you need offsets or milliseconds support in the future, extend the validation and helpers while preserving the current API surface.

Application Configuration Scope API

The applicationConfiguration scope exposes a filtered, read-only view of the host's runtime configuration (config.json) to plugins.

import {
  PluginManager,
  type ApplicationConfig,
  type ApplicationConfigurationState,
} from '@opengeoweb/plugin-interface';

// In the host app (GeoWeb): push the redacted config into the manager.
const filtered: ApplicationConfig = {
  frontend: {
    global: {
      sentryEnabled: true,
      initialPresetsFilename: 'default',
    },
  },
  backend: {
    trajks: {
      baseUrl: 'https://api.geoweb.example/v1',
      workspaceId: '123456789',
    },
  },
};
manager.setScopeState('applicationConfiguration', { geowebConfig: filtered });

// In a plugin: subscribe to the read-only state.
instance.onStateChange(
  'applicationConfiguration',
  (state: ApplicationConfigurationState) => {
    console.log(state.geowebConfig.backend.trajks.baseUrl);
  },
);

Notification Scope API

The notification scope lets a plugin push notifications (snackbars, banners, toasts) to the GeoWeb host. GeoWeb decides how to present them.

A plugin emits a notification with sendEvent:

import type { GeoWebPluginInstance } from '@opengeoweb/plugin-interface';

declare const instance: GeoWebPluginInstance;

instance.sendEvent('notification', {
  type: 'showNotification',
  severity: 'SUCCESS',
  content: 'Form published',
});

The host receives notifications through the standard scope subscription. The notification state starts as {} and is replaced by the event itself when one fires, so the state shape matches NotificationScopeEvent:

const unsubscribe = manager.subscribeToState('notification', (state) => {
  if (state.type) {
    showSnackbar(state.severity, state.content);
  }
});

The if (state.type) guard skips the initial empty replay before any notification has fired.

User Scope API

The user scope exposes read-only authentication and profile information to plugins.

import { PluginManager, type UserState } from '@opengeoweb/plugin-interface';

// In the host app (GeoWeb): push the user state into the manager.
const userState: UserState = {
  isLoggedIn: true,
  user: {
    username: 'john.doe',
    firstName: 'John',
    lastName: 'Doe',
    rolesPerIssuer: [
      {
        issuer: 'geoweb',
        roles: ['admin', 'editor'],
      },
    ],
  },
  hasConnectionIssue: false,
};
manager.setScopeState('user', userState);

// In a plugin: subscribe to the read-only state.
instance.onStateChange('user', (state: UserState) => {
  if (state.isLoggedIn) {
    console.log(`Welcome, ${state.user?.firstName}`);
  } else {
    console.log('User not logged in');
  }
});

Authentication Scope API

The authentication scope exposes low-level token details and credentials to plugins for fine-grained authorization decisions.

import {
  PluginManager,
  type AuthenticationState,
} from '@opengeoweb/plugin-interface';

// In the host app (GeoWeb): push the authentication state into the manager.
const authState: AuthenticationState = {
  tokens: [
    {
      issuer: 'geoweb-auth',
      token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      refreshToken: 'refresh_token_123',
      roles: ['admin', 'trajks:publish_form'],
      tokenExpiresAt: Date.now() + 3600000,
    },
  ],
};
manager.setScopeState('authentication', authState);

// In a plugin: subscribe to access token details.
instance.onStateChange('authentication', (state: AuthenticationState) => {
  const canPublishForm = state.tokens.some((token) =>
    token.roles.includes('trajks:publish_form'),
  );
  console.log('Can publish:', canPublishForm);
});

Both user and authentication are read-only from the plugin's perspective. Plugins cannot send events for these scopes; the host manages them via setScopeState.