FAQ

This FAQ contains short, cross-cutting answers that do not require a complete guide. For task-based instructions, use Guides. For detailed properties and methods, use the API reference.

Getting started

Q: Do I need to install anything to start building a Plugin?

No. You can build a Plugin two ways: in the Plugin Playground, which runs entirely in your browser with nothing to install, or in a local development environment using your own editor. The Playground is the quickest way to start and experiment; a local setup suits larger, more complex Plugins.

Q: What files does a Plugin need?

A Plugin requires a reearth.yml file (which describes the Plugin and its extensions) and one JavaScript file per extension. These are packaged together as a .zip.

Q: What’s the difference between a Widget, an InfoboxBlock, and a StoryBlock?

A Widget is placed in the main map view, where you can position it using the Widget Align System. An InfoboxBlock appears inside a feature’s infobox when a user selects that feature. A StoryBlock is embedded in a story page. See Differences between extension types for details.

Development

Q: When do I use “Install Dev Plugins” versus “Reload Dev Plugin Extensions”?

Use Install Dev Plugins for first-time setup and whenever you change reearth.yml. Use Reload Dev Plugin Extensions after changing your extension code. Changing reearth.yml needs a full install because it re-registers the Plugin’s structure.

Q: Why isn’t my Plugin’s UI showing up?

A Plugin’s UI is rendered by calling reearth.ui.show with your HTML. If nothing appears, check that you’re calling it, and that your extension’s JavaScript filename matches its id in reearth.yml. If the UI is showing but appears blank, check its styling: text can be invisible if its color matches the background, so set an explicit text color and background color on your UI.

Q: Can I use TypeScript?

Yes. Visualizer runs JavaScript, but you can write your Plugin in TypeScript and compile it to JavaScript. The recommended Plugin template is set up for TypeScript.

Capabilities and limits

Q: Why can’t my Plugin fetch data from an external API?

Requests to external servers must be made from the Plugin’s UI (the iframe side), not the extension logic (the WebAssembly side). The external server must also allow cross-origin requests by sending the Access-Control-Allow-Origin header, or the request fails.

Q: Why won’t a particular basemap or tile server load?

Some basemaps require a Cesium Ion access token. Others may fail if their tile server is unavailable or blocks cross-origin requests. If a basemap doesn’t appear, the tile source is often the cause.

Q: Is there a size limit for Plugins?

Yes. A Plugin must be packaged as a .zip of 10 MB or less. Non-JavaScript files such as images and CSS cannot be packaged inside the .zip: embed them in your JavaScript as strings, or host them on a publicly accessible server and reference them by URL.

Q: Can my Plugin store data that persists?

Local storage is not available, because the Plugin UI runs in a sandboxed iframe. To persist data, use the storage API provided by the Re:Earth Plugin API, or an external server.

Publishing and sharing

Q: How do I share a Plugin I built in the Playground?

Use the Share button to copy a link, or the Export button to download the Plugin as a .zip. Plugins too large to share by link can be exported as a .zip.