Files
worldwideview/docs/creating-a-plugin.md
T
silvertakana efa886ad3e feat: signal pending state for unverified plugin installs
install-redirect returns ?pending=pluginId for unverified plugins
instead of ?installed, so the marketplace can show correct status.
2026-03-18 18:26:24 +13:00

11 KiB

Creating a WorldWideView Plugin

This guide walks you through building, publishing, and listing your own WorldWideView plugin from scratch.


Overview

WorldWideView plugins display geospatial data on a 3D Cesium globe. Every plugin must implement the WorldPlugin interface from the Plugin SDK (@worldwideview/wwv-plugin-sdk).

There are three plugin formats:

Format Use Case Example
static GeoJSON file loaded at startup — no API calls at runtime Military Bases, Nuclear Facilities, Embassies
bundle Full TypeScript class with custom logic, live API data, UI components Aviation, Maritime, Wildfire
declarative JSON-only manifest that points to an external API — no code needed (Future)

Prerequisites

  • Node.js ≥ 18
  • npm account (for publishing)
  • The WorldWideView monorepo cloned locally

Step 1 — Create Your Plugin Package

All plugins live under packages/ in the monorepo.

mkdir packages/wwv-plugin-my-data
cd packages/wwv-plugin-my-data

Create package.json:

{
  "name": "@worldwideview/wwv-plugin-my-data",
  "version": "1.0.0",
  "description": "WorldWideView plugin — my custom data layer",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "files": ["src"],
  "keywords": [
    "worldwideview",
    "worldwideview-plugin",
    "geojson",
    "cesium",
    "globe"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/silvertakana/worldwideview.git",
    "directory": "packages/wwv-plugin-my-data"
  },
  "license": "ISC",
  "author": "WorldWideView",
  "peerDependencies": {
    "@worldwideview/wwv-plugin-sdk": "*"
  }
}

Important

The SDK is declared as a peer dependency, not a direct dependency. The host application provides it at runtime.


Step 2 — Write Your Plugin Code

Create src/index.ts. Here are examples for the two most common formats:

Option A — Static GeoJSON Plugin (simplest)

For static plugins, the npm package is just metadata. The actual loading is handled by the StaticDataPlugin loader at runtime, driven by a manifest + GeoJSON file.

/**
 * @worldwideview/wwv-plugin-my-data
 *
 * Static GeoJSON plugin — my custom dataset.
 *
 * This package exists for npm registry metadata. The actual plugin logic
 * is handled by WorldWideView's StaticDataPlugin loader at runtime using
 * the manifest + GeoJSON data file served from the host application.
 */
export const PLUGIN_ID = "my-data" as const;

For static plugins you also need:

  1. A GeoJSON file placed at public/data/my_data.geojson in the main app
  2. A manifest entry in the marketplace (see Step 4)

Option B — Bundle Plugin (full control)

For bundle plugins, you write a class that implements the WorldPlugin interface:

import type {
  WorldPlugin,
  GeoEntity,
  TimeRange,
  PluginContext,
  LayerConfig,
  CesiumEntityOptions,
} from "@worldwideview/wwv-plugin-sdk";

export class MyDataPlugin implements WorldPlugin {
  // ─── Required Metadata ──────────────────────────────
  id = "my-data";
  name = "My Data Layer";
  description = "Displays custom points on the globe.";
  icon = "MapPin"; // Lucide icon name (string)
  category = "custom" as const;
  version = "1.0.0";

  // ─── Lifecycle ──────────────────────────────────────
  async initialize(ctx: PluginContext): Promise<void> {
    // Called once when the plugin is loaded.
    // Use ctx.apiBaseUrl, ctx.timeRange, ctx.onDataUpdate, etc.
  }

  destroy(): void {
    // Called when the plugin is unloaded. Clean up timers, sockets, etc.
  }

  // ─── Data ───────────────────────────────────────────
  async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
    // Fetch your data from an API and return GeoEntity objects.
    const res = await fetch("https://api.example.com/points");
    const data = await res.json();

    return data.map((item: any) => ({
      id: String(item.id),
      pluginId: this.id,
      latitude: item.lat,
      longitude: item.lon,
      altitude: 0,
      timestamp: new Date(),
      label: item.name,
      properties: { type: item.type },
    }));
  }

  getPollingInterval(): number {
    return 60_000; // Re-fetch every 60 seconds
  }

  // ─── Rendering ──────────────────────────────────────
  getLayerConfig(): LayerConfig {
    return {
      color: "#3b82f6",
      clusterEnabled: true,
      clusterDistance: 40,
      maxEntities: 5000,
    };
  }

  renderEntity(entity: GeoEntity): CesiumEntityOptions {
    return {
      type: "point",
      color: "#3b82f6",
      size: 8,
    };
  }
}

Step 3 — Publish to npm

cd packages/wwv-plugin-my-data
npm publish --access public

Note

The marketplace pulls metadata (version, description, keywords) directly from the npm registry at runtime. You do not need to duplicate this metadata in the marketplace.


Step 4 — Register in the Marketplace

4a. Add to knownPlugins.ts

Open worldwideview-marketplace/src/data/knownPlugins.ts and add your plugin:

{
  id: "my-data",
  npmPackage: "@worldwideview/wwv-plugin-my-data",
  icon: "MapPin",              // Lucide icon name
  category: "Custom",          // Must match a value in CATEGORIES
  format: "static",            // "static" | "bundle"
  trust: "verified",           // "built-in" | "verified" | "unverified"
  capabilities: ["data:own"],
  longDescription:
    "Description shown on the plugin detail page in the marketplace.",
  changelog:
    "v1.0.0 — Initial release.",
},

4b. Add a manifest (static plugins only)

For static format plugins, open worldwideview-marketplace/src/data/pluginManifests.ts and add:

"my-data": {
  id: "my-data",
  name: "My Data Layer",
  version: "1.0.0",
  description: "My custom data layer",
  type: "data-layer",
  format: "static",
  trust: "verified",
  capabilities: ["data:own"],
  category: "Custom",
  icon: "MapPin",
  dataFile: "/data/my_data.geojson",   // Path to GeoJSON in public/
  rendering: {
    entityType: "point",
    color: "#3b82f6",
    labelField: "name",
    clusterEnabled: true,
    clusterDistance: 50,
    maxEntities: 5000,
  },
},

Bundle plugins do not need a manifest entry here — their code is loaded via dynamic import.


Step 5 — Test Locally

  1. Start the WorldWideView app: npm run dev (in the worldwideview directory)
  2. Start the marketplace: npm run dev (in the worldwideview-marketplace directory)
  3. Open the marketplace at http://localhost:3001/browse
  4. Find your plugin and click Install
  5. Verify the data appears on the globe at http://localhost:3000

SDK Interface Reference

The WorldPlugin interface requires these properties and methods:

Required Properties

Property Type Description
id string Unique plugin identifier (e.g., "my-data")
name string Display name shown in the sidebar
description string Short description
icon string | ComponentType Lucide icon name or React component
category PluginCategory One of: aviation, maritime, conflict, natural-disaster, infrastructure, cyber, economic, custom
version string Semver version string

Required Methods

Method Returns Description
initialize(ctx) Promise<void> Set up the plugin. Receives PluginContext with API URLs, time range, callbacks
destroy() void Clean up resources (timers, sockets, etc.)
fetch(timeRange) Promise<GeoEntity[]> Return the data to display on the globe
getPollingInterval() number Milliseconds between fetch() calls
getLayerConfig() LayerConfig Layer appearance (color, clustering, limits)
renderEntity(entity) CesiumEntityOptions How each entity renders on the globe

Optional Methods

Method Returns Description
getSelectionBehavior(entity) SelectionBehavior | null Trail / fly-to on click
getServerConfig() ServerPluginConfig Server-side API routing
getFilterDefinitions() FilterDefinition[] Declarative filter UI
getSidebarComponent() ComponentType Custom sidebar panel
getDetailComponent() ComponentType<{ entity }> Custom detail panel
getSettingsComponent() ComponentType<{ pluginId }> Custom settings panel

Key Types

interface GeoEntity {
  id: string;
  pluginId: string;
  latitude: number;
  longitude: number;
  altitude?: number;
  heading?: number;
  speed?: number;
  timestamp: Date;
  label?: string;
  properties: Record<string, unknown>;
}

interface LayerConfig {
  color: string;
  iconUrl?: string;
  clusterEnabled: boolean;
  clusterDistance: number;
  minZoomLevel?: number;
  maxEntities?: number;
}

interface CesiumEntityOptions {
  type: "billboard" | "point" | "polyline" | "polygon" | "label" | "model";
  color?: string;
  size?: number;
  iconUrl?: string;
  rotation?: number;
  modelUrl?: string;
  modelScale?: number;
  // ... more options
}

Real Examples

Borders Plugin (bundle format)

A minimal bundle plugin that implements the WorldPlugin interface directly:

  • Source: packages/wwv-plugin-borders/src/index.ts
  • npm: @worldwideview/wwv-plugin-borders

Military Bases Plugin (static format)

A static GeoJSON plugin where the npm package is just metadata:

  • Source: packages/wwv-plugin-military-bases/src/index.ts
  • GeoJSON: public/data/military_bases.geojson
  • npm: @worldwideview/wwv-plugin-military-bases
  • Manifest: Defined in worldwideview-marketplace/src/data/pluginManifests.ts

How It All Connects

Developer writes plugin
        │
        ▼
Publish to npm ──────────────────────────────────►  npm registry
        │                                            │
        ▼                                            │
Add to knownPlugins.ts ──►  Marketplace ◄────────────┘
(+ pluginManifests.ts        shows plugin       (fetches version,
 for static plugins)         in browse grid      description, etc.)
                                  │
                                  ▼
                           User clicks "Install"
                                  │
                                  ▼
                       Marketplace sends manifest
                       to WorldWideView instance
                                  │
                                  ▼
                       InstalledPluginsLoader saves
                       manifest to database (Prisma)
                                  │
                                  ▼
                       loadPluginFromManifest() routes
                       by format: static → StaticDataPlugin
                                  bundle → dynamic import
                                  │
                                  ▼
                       Plugin renders on the 3D globe