Set up a local development environment

Note

This section describes the current template-based workflow. The Re:Earth Visualizer Plugin CLI is not currently available.

The Plugin Playground is ideal for quick experiments, but use a local development environment to build a full Plugin. This setup lets you write your Plugin in your own editor and see your changes in Re:Earth Visualizer almost instantly—without manually building and reinstalling the .zip each time.

This workflow has two halves: a Plugin project created from a template, and a local Re:Earth Visualizer that loads your Plugin directly from a preview server using the DEV_PLUGIN feature.

Prerequisites

This guide assumes you already have Re:Earth Visualizer running locally and accessible at http://localhost:3000. Setting up the Visualizer itself (including its server and database) is a separate process—for instructions, see the reearth-visualizer repository.

Also install Node.js and Yarn.

Create a Plugin from the template

The recommended starting point is the Re:Earth Visualizer Plugin ShadCN Template, built with React, ShadCN, and Tailwind CSS.

Note

The template is a convenient starting point, not a requirement. You can build your Plugin with any framework or library you prefer. The essential part of this workflow is the DEV_PLUGIN feature, which loads your Plugin from a local preview server.

After creating your own copy of the template and opening it in your terminal:

1. Move into your Plugin directory:

   cd your-new-plugin

2. Install the dependencies:

   yarn install

3. Run an initial build to generate the required files:

   yarn build

4. Start the development and preview server:

   yarn dev-build

This last command watches your code, rebuilds the Plugin automatically when you save, and serves it from a preview server at http://localhost:5005.

Enable DEV_PLUGIN in Re:Earth Visualizer

Next, tell your local Visualizer to load the Plugin from that preview server.

1. In your local Re:Earth Visualizer project, move into the web directory and create a .env file if one does not already exist:

   cd web
   touch .env

2. Add the preview server URL to the .env file:

   REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'

The web server restarts automatically after you save changes to .env.

Add a widget Plugin to a project

With both servers running, set up a project in the Visualizer to host your Plugin:

1. Open your local Re:Earth Visualizer at http://localhost:3000.
2. Create a new project from the dashboard.
3. Double-click the project to open it.
4. In the editor header, click Install Dev Plugins to fetch and install your Plugin from the preview server.
5. Open the Widgets tab and add your Plugin’s Widget to the scene.

Note

These steps apply to Widget extensions. Plugins with InfoboxBlock or StoryBlock extensions are installed the same way (steps 1–4), but are added to a scene from a layer’s infobox settings or a story page instead of the Widgets tab. See Differences between extension types for where each type appears.

The development loop

Once everything is connected, your day-to-day workflow becomes very short:

1. Make a change to your Plugin code and save it. The Plugin rebuilds automatically.
2. In the Visualizer editor header, click Reload Dev Plugin Extensions to load the updated Plugin.

Because only the Plugin reloads—not the entire page—your changes appear almost immediately.

The two dev Plugin buttons

The DEV_PLUGIN workflow adds two buttons to the Visualizer editor header. Both are puzzle-piece icons:

• Install Dev Plugins: Fetches your Plugin from the preview server, packages it into a .zip, and installs it.
• Reload Dev Plugin Extensions: Reloads your Plugin’s extension code from the preview server without reloading the page.

Use this guide to decide which one to click:

What you changed	Button to use
First-time setup in a project	Install Dev Plugins
Extension code (TypeScript / JavaScript)	Reload Dev Plugin Extensions
reearth.yml (the Plugin manifest)	Install Dev Plugins