Add a new CLI to help new users configure a new project faster: `msw config`

[nvh95]

Scope

Adds a new behavior

Compatibility

• [ ] This is a breaking change

Feature description

Motivation

• Whenever I need to integrate msw to a new project. I follow the installation guide at https://mswjs.io/docs/getting-started/install. It took me about 15-30 minutes to get through 5-7 pages, from installing the library, defining mocks, integrating with browser and nodejs, then verifying if it works properly.
• It will be nice if we have a CLI, for example: msw config (Name to be discussed) to do all the above work for new users. We can leverage inquirer to make it interactive by asking people if they want to integrate to REST or GraphQL, Browser or Node or both...

Why this feature needed

• It significantly reduced the time newcomers need to configure a new project.
• It potentially attracts more users. People might know about msw but haven't tried it yet. If they only need to run only one command to get it running. They might give msw a try.

How to implement it

• Add a new CLI under cli folder. Use inquirer to ask users about their preferences. Then automatically generate the boilerplate code at the beginning.
• The CLI contains many tests, try/catch at each step to make sure they can continue to configure if the CLI crashes. Show reference in the documentation if the CLI throws an error at one step.

Similar feature

When developing Jest Preview, to configure for Create React App would be a nightmare. So I made a CLI jest-preview config-cra. More at https://www.jest-preview.com/blog/first-class-support-cra

Can I help with this feature?

Yes. 100%. I would love to help with this feature. Actually, I am reading the project source code in general and this is my first initiative pops up in my head.

[kettanaito]

Hey, @nvh95. Thanks for proposing this!

So, do I understand it correctly the expected behavior of such a CLI command is the following:

$ npx msw init

> Which language do you use? (auto-detected: TypeScript): TypeScript
> Which API would you like to mock?
  - REST API
  - GraphQL API
  - Both
> Where to place the "mocks" directory? ./src
> Where would you like to enable mocking?
  - Node.js (i.e. Jest/Express/React Native)
  - Browser (i.e. runtime/Cypress/Playwright)
  - Both

Successfully generated a new setup at "./src/mocks"!
  
  - src/mocks/**handlers.ts**
    Lists request handlers that describe the network behavior.
    Learn more: https://mswjs.io/docs/basics/request-handler

  - src/mocks/**browser.ts**
    Enables API mocking in the browser by registering and
    activating a Service Worker.
    Learn more: https://mswjs.io/docs/api/setup-worker

I always support shipping features that help people integrate MSW into their projects. At the same time, we need to be careful how "smart" this CLI is/could become. This raises the question of the completeness of this process:

• Do you expect to perform additional actions after running this command?

For example, in order to have a fully functional integration testing setup, you'd have to import and start the server from the generated src/mocks/server.ts. But the testing setup depends on the testing framework. While we could try guessing which framework you're using, and what's the best config to produce, it becomes increasingly difficult to predict certain things. This is a red flag for me for a physically incomplete API that will likely not work for certain users.

The actual task here is to find the proper balance between convenience and auto-guessing. I'm open to feedback on where you think that balance lies. Perhaps, defining the target developer could help us with that balance, as I can presume the target developer uses CRA/Next/Gatsby and does not have a ton of custom configurations around.

[nvh95]

@kettanaito Thank you for your very quick feedback

I get your idea and I will think about it more. We cannot make a CLI "100% works" in every case. My goal is to reduce their time configuring, so a new user can use msw "as fast as possible". We can support them to add some code, maybe also a few comments. And they always know that they can update/ adjust the generated code to fit their use case.

Do you expect to perform additional actions after running this command?

That's a very good question. For now, I don't know. Guessing a framework to produce corresponding code (and just show documentation if we fail to guess) is a good idea. But we can always have a fallback to show them the documentation at any time. I guess we can just start small

I'm not so sure about automatically adding the worker.start() and server.listen() at the moment. But I strongly believe we can aid them add some code for Rest/ GraphQL + Node/ Browser for now.

So, let's pretend I am a new developer who just heard about msw. I am lazy enough not to read the full documentation. (But luckily, I know msw config exists 😂). I will do as following:

• yarn add -D msw
• npx msw config, we can help him with most of the boilerplate, and SHOW him an important documentation link for him to finish his setup (add worker.start() or server.listen())

I will try to make a PoC to see how it will go. Then we can discuss more on what is the best to implement this feature.

[kettanaito]

The issue is that

I am lazy enough not to read the full documentation.

is a very dangerous premise. Developers who are lazy to read documentation will encounter dozens of issues even if we provide them with the state of the art CLI. Because, in the end of the day, it's the developer who makes decisions and has to set up things.

I don't mind reducing the boilerplate but for that official templates exist for Next, and a bunch of examples that are ready-to-be-cloned.

Let's discuss the scope of this CLI command before jumping to any proofs of concept so there's no contribution energy wasted. I will try posting my expectations in a form of a spec in the days to come.

[kettanaito]

I'm closing this due to the lack of discussion. MSW CLI is extremely tiny and it doesn't take too much time to read through its docs. There's really 1 command you need: msw init, which is extremely straightforward to use.

We likely won't ship it as a part of the MSW package. Volunteers are welcome to create their own packages that help others set up MSW if they have difficulty with that. Thanks for understanding.