Command line interface

[vgeorge]

Contributes to #120.

We are investigating a tool starter for VEDA in this issue.

This is a work in progress and not intended to be merged here (unless we decide to do so later).

The general idea is to provide an easy way to generate a web map SPA scaffold. It makes sense to base it on project-seed, as we typically use it to start our projects.

I created a /cli folder without touching existing files. This folder contains the generator and the templates for different variants.

What’s included:

• CLI generator using Commander.js and Inquirer
• Base template
• Component library variants: none, Chakra UI, React USWDS
• Template merging system that combines base + selected component library

By default, the generator creates a scaffold identical to project-seed. But it also allows creating with different component libraries. The next step would be to offer mapping library variants, for example, MapLibre and Mapbox.

This is very exploratory work, happy to hear any feedback.

cc @aboydnw @dzole0311 @AliceR

[dzole0311]

@vgeorge could you add some details on how to run the cli setup? I'm seeing some issues wrt module resolution.

[vgeorge]

@dzole0311 I have updated the file cli/README.md with instructions on how to run the cli. I'll be adding more changes to this, but you should be able to generate websites with the component library variants.

[vgeorge]

This is ready for review. I’ve made significant changes, so it’s important to check where we stand and confirm we’re heading in the right direction.

The README should now clearly cover the CLI instructions and overall approach. I recommend running pnpm generate-all and testing the apps in the cli/generated folder.

cc @dzole0311 @AliceR

[dzole0311]

Thanks @vgeorge, this is a good starting point and I have no specific comments around the current structure.

Just to expand on what I meant in NASA-IMPACT/veda-ui#1749 (comment) I think there’s potential in VEDA to go beyond a basic SPA map scaffold e.g. imagine a developer working on a flood viewer: they would benefit from a setup they can build on without starting from scratch:

1. Run an initial CLI command to scaffold a base app (already done here ✅ )
2. a) Choose from a few layout presets, or b) run additional CLI commands to inject optional modules like:

• layer switchers
• timeline/timerange selector with playback controls
• custom map config (e.g. with or w/o deck.gl)
• configure layout slots or UI positions for these injected modules

In other words, the only real value I see in a CLI tool like the one we discussed is to let devs focus on domain-specific logic and data visualization (e.g. "now that I have a scaffold with layer switchers, map viewer and playback controls, I can go straight to visualizing flood dynamics or implementing that custom Deck.gl layer for water rise we really need"), rather than spending time wiring up basic UI components each time, for each simple tool. The result would be a composable UI shell that can be extended / tailored by doing customization on the base scaffold.

I think the main effort would be to identify and package ~7–10 common geospatial UI components, things like layer toggles, legends, time controls, etc and make them injectable via the CLI.

Also, since the whole conversation of "faster tool development" is currently only around VEDA which uses USWDS, if we want to move fast with the PoC it might make sense to further scope this and assemble the components using react-uswds primitives to keep things opinionated.

[vgeorge]

Thanks for the feedback, @dzole0311. I agree that we can expand the scaffolding capabilities of this CLI tool, but since this PR is already quite large, I suggest we track further enhancements separately.

For now, I’d like to propose merging this and using it to replace the current project-seed setup. As mentioned above, I believe this version is in a good state to serve as a replacement.

I'm putting this under review by the broader frontend team (especially @danielfdsilva), and I’ll demo it during our next frontend meeting.

Next steps:

• Review the contents in /cli (documentation, ability to generate a scaffold app)
• Replace the root folder with its contents
• Bump the version to v9 and release

[AliceR]

Thanks for the effort here @vgeorge ! This could become very useful. IMO a couple of baseline QA tools are missing:

• prettier formatting (probably run via eslint, see https://prettier.io/docs/integrating-with-linters.html)
• Stylelint for CSS linting alongside ESLint
• git hooks (likely husky pre-commit npm run lint and pre-push npm run test:run)
• Log accessibility violations in development mode with @axe-core/react to automatically detect and log accessibility issues to the console when running in development mode. This expands the static evaluation of JSX with eslint-plugin-jsx-a11y.
• a basic ci.yml to run lint and test on Github

We could add all these in iteration and after discussion, but I worry that if we do not take the chance now, we might never take the extra effort and add them to the generated projects later.

Edit: I looked at the wrong package.json, prettier and Stylelint are already set up!

[vgeorge]

I’ve pushed changes to address the issues noted by @danielfdsilva, this is ready for another review.

@AliceR Thanks for the feedback. I’ve created an epic ticket (#120) to track ongoing work on the CLI and to capture your proposed changes there. Since this PR already introduces a significant number of changes, I believe it makes sense to merge it into the develop branch and track the remaining work in the epic ticket.

[vgeorge]

@AliceR I removed the ESLint custom rule. I also added a missing dependency of the chakra template.

[AliceR]

@vgeorge I noticed an issue with the path resolution in dev vs. prod. #121 should fix it!

[AliceR]

IMO this is solid enough to merge to develop! 👏 We can iterate from there, or leave cli as base for further changes, I don't mind the difference :)

[vgeorge]

@AliceR lets continue from develop, thanks for the changes 🙂