Tool starter proof of concept

[aboydnw]

Context

As we start developing more and more tools, we will need to be able to develop tools faster and with more consistency.

Some ideas we have been discussing to resolve this:

• Tools built with plug-ins that can be configured with a set of props
• Reusable components that developers can use to quickly build parts of tools that are frequently similar
• A tool "starter" to help a developer quickly spin up a tool with some basic configurations and components, to speed up the development cycle and set a standard layout and framework for customization to take place

This ticket is to build a proof of concept of the tool starter. In this work, we are making a few assumptions:

1. Every tool we develop will need some level of customization, to meet the custom needs of the data it is visualizing
2. We can standardize the visual layout of tools
3. There are some basic tool needs that can be met with resuable components

Acceptance Criteria

• A proof of concept demoing the tool starter flow with some basic options. This is open to interpretation based on feasibility and value, but the overall goal is to have something quickly that shows the idea and intent.

Definition of Done

• Unit tests
• (Where applicable) Automated playwright tests to cover primary use case(s)
• Merged to develop in relevant repo
• (?) Tested in instance context (GHG, earth.gov, template instance, etc)
• Relevant details of work are shared in a team forum (PR, ticket, slack, etc) to support knowledge sharing

[aboydnw]

@ajinkyakulkarni FYI we will be exploring this idea over the next couple weeks. I think it's related to your work on plug-ins, so we'll want to collaborate.

[dzole0311]

Adding some more thoughts to help with scoping. Let's see whether we can add/re-use, or change up some of the things below.

Concept

The idea is to develop a CLI-like tooling similar to Vite (e.g. "geo-vite"), but focused on quickly bootstrapping VEDA geo apps/tools with sensible defaults and re-usable components.

Example command inspired by Vite:

npm create geo-vite@latest my-new-tool -- --template <template-name>

Running the command will ask a few questions to help the bootstrapping, such as:

1. Basemap library (options: Mapbox, Maplibre)
2. Should include Deck.gl? (options: yes, no)
3. Initial layout (e.g. options: side panel + map, top bar + full map, map only)
4. Include simple time control components? (options: scrubber, animation toggle, time range selector)
5. Include sample layer from VEDA? (e.g., MVT or GeoJSON layer)
6. Include common utilities? (e.g., layer toggle menu, legend, download panel, settings modal)
7. Preferred styling system? (e.g., for the PoC we can stick to USWDS, but could extend to Tailwind, plain CSS modules, etc)

To test this out, we can re-use some existing geospatial components from veda-ui, the Fire Event Explorer, or other projects. The tooling can have a few official templates that we can support + possibility for community driven templates.

What success looks like:

• One (or few) working template(s) that:
  • Scaffold a new Vite app with, for example, Mapbox + Deck.gl + a working UI shell
  • Include 1–2 dummy layers, sidebar, basic interactions (popup on hover/click)
• Output runs via npm run dev with no additional manual config

Out of scope for now (stretch goals):

• Managing datasets or integration with backend APIs
• State management libraries (the context API could work)
• Complex theming or branding setup

Why this matters

• Reduce the time to first map
• Make it easier for engineers and teams to scaffold tools
• Standardize the look, feel and code structure across VEDA

[vgeorge]

While the idea of a generator sounds exciting, I don't see, at least for now, a high enough frequency of new tools being created to justify a more elaborate technical setup and the required maintainance.

I'd be more in favor of something like https://github.com/developmentseed/project-seed, which already helps kick off projects with sensible defaults for ESLint, TypeScript, testing, GitHub Actions, etc.

If VEDA tools are mostly simple map SPAs, we could even stick with Project Seed and evolve it to match the specific needs here.

[AliceR]

Project-seed is now built on a solid, modern foundation (Vite, Chakra, ESLint, Jest, CI) and could definitely serve as a strong base for future tools.

One concern I have with project-seed is that, as a GitHub template, it locks in dependency versions at the time it’s copied. Without regular maintenance or upgrade guidance, this could lead to stale setups over time. It also doesn’t support dynamic prompts or conditional scaffolding like npm create vite@latest, which limits flexibility for things like layout or library choices.

This would be solved by wrapping project-seed in a lightweight CLI, like @dzole0311 suggests, that injects some setup interactivity while still pulling from the latest template.

But I agree with @vgeorge though, before investing too much time in a CLI tool we need to ask, how often are new tools being created? If it's infrequent, a well-maintained GitHub template plus upgrade docs might be more sustainable than building and maintaining a custom CLI.

I’d like to strike a balance: keep things easy to maintain long-term, while helping devs scaffold tools quickly without worrying about outdated dependencies.

Has anyone used project-seed recently? Does it currently fit the bill? What would we need to adjust for our use case?

[vgeorge]

I gave it some more thought and agree with @dzole0311 that a CLI is better suited for generating different tools, rather than maintaining fixed templates.

I've started an exploratory implementation using project-seed: developmentseed/project-seed#118.

It’s a CLI that lets you select between different component libraries (Chakra, USWDS, or none). The next step is to add support for generating a web map app using MapLibre or Mapbox.

@AliceR in this implementation, lock files are generated at creation time, so they can capture minor upgrades as long as we define the versions properly.

[vgeorge]

In the last Data Systems Evolution meeting, there were two demos on ongoing projects showing different approaches to building custom tools for dashboards. Here’s a quick summary of each:

Veda-Tools (React Component Library)

A React-based library with reusable UI components and full interfaces. Designed to simplify reuse across apps.

How it works:

• Install via npm
• Import components or full UIs into any React app
• Can also be embedded in CMS platforms like Drupal (build the bundle, mount via script)

Presented goals:

• Speed up UI development by reusing components
• Keep interfaces consistent across tools
• Centralize updates to shared components

Example:
A “Cloud Browse” interface was shown running in both a React app and a Drupal setup.

Plugin Framework for Geo Viz Tools

A CLI-based framework where dashboard features are added through plugins. Each plugin contributes to a specific part of the layout.

How it works:

• Start with a minimal app shell
• Use a CLI to install and configure plugins (via manifest files)
• Plugins define where they render (e.g., top panel, map, sidebar) and communicate with the app via an event bus

Presented goals:

• Make the system modular and extensible
• Allow reuse of plugins across different tools
• Enable feature development without modifying core code

Example:
The demo showed plugins for a header, wind particle map, dataset manager, and video recorder. Each was installed and configured via CLI and appeared in the layout automatically.

Moving forward with the Tool Starter

There’s a fair bit of overlap between the tool starter we’re building and the tools shown in the demos, especially around reuse, consistency, and reducing the overhead of building new tools.

But the Tool Starter approach has a slightly different focus. The main goal of the tool starter is to give developers a scaffold, something to get things up and running quickly with a base layout, core components, and enough flexibility to build more complex, tailored tools on top. It’s meant to save time without adding too many constraints.

From what was demoed, Veda-Tools seems more geared toward quickly embedding prebuilt UIs into existing apps or CMSs. The plugin framework, while modular, feels more focused on composing lighter tools via CLI and config, and maybe less suited for cases where you want more control over layout, styling, or logic.

So while the core ideas are similar (modularity, reuse, speed), the tool starter leans more toward developer flexibility and building fully custom tools.

In the proof-of-concept PR, we already have a working CLI that can scaffold a new tool. A couple of questions as we move forward:

1. Since the tool starter seems to align with the goals of project-seed, should we propose an RFC to fold it into project-seed, or should we fork it into a separate project? This would have the benefit of building on top of an existing tool that could benefit other devs at DevSeed and possibly outside as well.

2. How far do we want to go with customization options in the starter? Gjore suggested adding more layout and component presets. I’d lean toward an MVP first and expand as needed. What do we consider the minimum?

cc @aboydnw @dzole0311 @AliceR @snmln @hanbyul-here @sandrahoang686

[hanbyul-here]

Thanks for the great write up @vgeorge 🙇
I think we are going a bit ahead of what is needed. For example, I expect the tools starter to have a bit more jump starters geared towards the geospatial tools in the future, but only after VEDA UI actually has a set of those components. We definately have to align with other teams better - but at this point, I wonder if tool starter can actually help plugins creator better. It could be just one more layer of complexity, or tool creator can be an interface that can be either used by a developer or plugin creator.

[vgeorge]

Thanks for the feedback, @hanbyul-here. Considering there are already two existing tools (listed above), I'm concerned our work on the CLI tool might not be absorbed by the other teams. I agree that we need to take a step back and assess what we have and how to move forward.

Some information that could help us as we move ahead:

• Links to the source code for Veda-tools and the Plugin Framework for Geo Viz Tools (@aboydnw, do you know where we can find these?)
• Analyze the codebases
• Regroup and decide whether we want to push a third tool or contribute to the existing ones

[aboydnw]

Just to comment here on a convo we had during checkin:

We are using the Water Insights tool as a test case of the plugin tool that UAH prototyped last PI. We will be pausing our work on the tool starter until at least after that development phase. My guess is that will take the rest of the PI.

So, we should wrap up our work we have done so far. I think merging the PR that you had been working on @vgeorge (after review) would be a good final step. Then we will likely move into other tickets and Earth Information Explorer development.

[aboydnw]

Assuming we can close with developmentseed/project-seed#118 closed