install-redirect returns ?pending=pluginId for unverified plugins instead of ?installed, so the marketplace can show correct status.
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:
- A GeoJSON file placed at
public/data/my_data.geojsonin the main app - 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
- Start the WorldWideView app:
npm run dev(in theworldwideviewdirectory) - Start the marketplace:
npm run dev(in theworldwideview-marketplacedirectory) - Open the marketplace at
http://localhost:3001/browse - Find your plugin and click Install
- 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