PROPOSAL: single-spa CLI

[MilanKovacic]

Proposal for single-spa CLI Introduction

Summary

This proposal advocates for the introduction of a single-spa Command Line Interface (CLI) to streamline the project setup and configuration process within the single-spa ecosystem. Currently, create-single-spa serves as the primary utility for initializing single-spa projects. The new CLI aims to not only replace create-single-spa but also provide a unified and simplified interface for creating, developing, and building single-spa projects. It seeks to address the challenge of default exposure of not just webpack configuration but also other infrastructure settings such as Babel config to all users, regardless of their need for customization.

Problem

The current state of tooling in the single-spa ecosystem presents several challenges:

1. Overexposure of Configuration: The default setup exposes webpack, Babel, and other infrastructure configurations to all users. This broad exposure can overwhelm those who do not require direct access or customization, leading to a steeper learning curve and potential misconfigurations.
2. Lack of a Unified Tooling Experience: With the existing create-single-spa utility focusing primarily on project initialization, there is a noticeable absence of a comprehensive tool that encompasses a broader range of development activities. A unified CLI could significantly enhance the developer experience by streamlining project creation, development, and build processes.
3. Increased Risk of Configuration Drift: The direct exposure of critical configurations such as webpack and Babel across different development environments and projects can lead to configuration drift. This drift complicates maintenance and standardization efforts, hindering collaboration and project scalability.

Solution

The proposed single-spa CLI is designed to tackle these issues effectively:

• Unified CLI Interface: Replacing create-single-spa, the new CLI will offer an integrated solution for project management, including creation, development, and build processes. This unified approach aims to simplify the development workflow, making the single-spa ecosystem more approachable and user-friendly.
• Selective Configuration Exposure: The CLI will adopt a more selective approach to exposing configurations, hiding complex setup details like webpack and Babel configurations by default. This method ensures that such configurations are only made available to developers who explicitly require them, thus reducing the initial complexity for newcomers.
• Advanced Customization Without Overwhelm: Introducing a customization mechanism for webpack and Babel configurations (among others) that mirrors the approach used by NestJS. This method will allow developers to adjust the default setup through specific functions without the need to sift through the entire configuration. It will enable the inclusion of necessary modifications and plugins, catering to the needs of advanced users without cluttering the experience for those seeking simplicity.

By addressing these challenges, the proposed single-spa CLI aims to enhance the overall development experience within the single-spa ecosystem, offering a balance between simplicity for beginners and powerful customization options for experienced developers.

[ibacher]

I agree that the amount of configuration exposed via create-single-spa may be overwhelming to beginners and there's some low-hanging fruit that can be done there. I'd want to know a little bit more about the scope of the proposed "Advanced Customization"; I'm not really familiar with NestJS, but this seems like the area where the tooling is most likely to get a bit out of hand.

[MilanKovacic]

By default, the development script could be something like:

"start:dev": "single-spa build" (which would use a default single-spa managed webpack configuration)

For projects requiring changes to webpack configuration, they could do something like:

"start:dev": "single-spa build --webpack-configuration custom-webpack-configuration.js"

Where we would then inject internal webpack configuration, and allow customers to customize, it similar to:

https://docs.nestjs.com/recipes/hot-reload#configuration

Some examples:

https://docs.nestjs.com/cli/overview
https://nextjs.org/docs/pages/api-reference/next-cli
https://docs.astro.build/en/reference/cli-reference/

[joeldenning]

I'm pretty hesitant about going down the path of Angular / Vite / Next / etc where they hide the bundler config, lint config, test config, etc etc within node_modules.

I'm open to a single-spa command that encompasses more than just the npm init single-spa that is currently supported via create-single-spa, but would want to discuss exactly which commands are supported and the implications for existing and new users.

Managing bundler configuration within node_modules is tempting, but I've been in the node_modules bundler configs for single-spa contracting consultants enough to know that we should be cautious about it. Surfacing configuration to single-spa end users is a good thing. I would prefer code mods updating the configuration in many cases, rather than upgrading an npm package that is hiding dozens of configuration files. The Angular way of burying configuration was so horrible to integrate with single-spa - it will be hard to convince me to go down the same path.

JS devs in 2024 are past JS fatigue into "can AI do my job for me" and so there are fewer developers willing to go read webpack documentation than in the past. We should seek an improved DX for single-spa users, but I'd prefer not discarding the current userbase's way of doing things and also would prefer letting users manage the raw configuration rather than constantly opening github issues on single-spa CLI to be able to change their jest configs.

[joeldenning]

After discussing this further with Milan during the monthly core team meeting, we've decided to proceed with a proposal and proof of concept for it. In 2024, we probably need to simplify the DX to be able to be viable compared to alternatives, even though I don't like hiding configuration

[alex-enchi]

While I agree that cli would be nice for fresh projects but hiding configuration means much harder time for existing projects to migrate. Is it possible to have a cli tool but keep minimal configuration as visible as possible?

I’m quite reluctant to add another cli tool into the toolchain