@reearth/visualizer-plugin-api

TypeScript type definitions for the Re:Earth Visualizer plugin API.

Installation

npm install --save-dev @reearth/visualizer-plugin-api @reearth/[email protected]
# or
yarn add -D @reearth/visualizer-plugin-api @reearth/[email protected]

@reearth/core is a peer dependency, pinned to the version the Visualizer runs (0.0.7-alpha.81). Install that exact version, not latest, so the types match the Visualizer. Install it alongside this package so TypeScript can resolve the layer and feature types used in the declarations.

Note: @reearth/core brings React and Cesium with it (about 350 packages), only for the type imports.

Usage

Create a reearth.d.ts file in your plugin project:

import type { Reearth } from "@reearth/visualizer-plugin-api";

declare global {
  const reearth: Reearth;
}

Then use reearth with full TypeScript IntelliSense:

reearth.camera.flyTo({ lat: 35.68, lng: 139.76, height: 1000 });
reearth.layers.show("layer-id");
reearth.ui.show("<h1>Hello from plugin</h1>");
reearth.camera.on("move", (pos) => console.log(pos.lat, pos.lng));

API Overview

TypeScript configuration

Add "skipLibCheck": true to your tsconfig.json. This package depends on @reearth/core, which references React and Cesium types internally. Without skipLibCheck, those transitive declarations cause errors in projects that do not install React or Cesium types directly.

Versioning

This package version tracks the Re:Earth plugin API version directly. @reearth/[email protected] corresponds to plugin API version 2.1.0. When the plugin API version bumps, a new version of this package is released with the same version number.

See CHANGELOG.md for the full history.

Source of truth

This package is the single source of truth for the plugin API types. The Visualizer web app (web/) imports them from here, so there is no second copy to keep in sync. To change the API types:

1. Edit visualizer-plugin-api/src, bump the version in package.json, and update CHANGELOG.md.
2. Release the package (see below).
3. Update the @reearth/visualizer-plugin-api version in web/package.json and run yarn install.

To try a change in web/ before releasing, build the package (npm run build) and point web at it with yarn add @reearth/visualizer-plugin-api@portal:../visualizer-plugin-api. Do not commit that; the web Dockerfile only builds from web/.

When @reearth/core is upgraded in web/, upgrade the pinned peer version here and release too.

Releasing

Publishing uses npm OIDC Trusted Publishing — no NPM_TOKEN needed.

One-time SRE setup

1. Create the npm-publish environment on this GitHub repo with a required reviewer (Settings → Environments → New environment). Restrict deployment refs to tags matching visualizer-plugin-api-v*.
2. Configure OIDC Trusted Publishing on npmjs.com for @reearth/visualizer-plugin-api:
   • Repository: reearth/reearth-visualizer
   • Workflow filename: plugin_api_release.yml
   • Environment: npm-publish

First publish (manual — one time only)

The package name must be claimed on the registry before Trusted Publishing can take over:

cd visualizer-plugin-api
npm publish --access public

Subsequent releases

1. Bump the version in visualizer-plugin-api/package.json and update CHANGELOG.md.
2. Go to GitHub Actions → Publish @reearth/visualizer-plugin-api → Run workflow.
3. Enter the version number (must match package.json) and confirm.
4. Approve the manual gate in the npm-publish environment.

License

Apache-2.0