search

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation
https://storybook.js.org
MIT License
84.73k stars 9.33k forks source link

Discussion: CLI Overhaul #10723

Closed yannbf closed 4 years ago

yannbf commented 4 years ago

What is this?

This is an issue to center the status and discussions about the work that's being done at #10702.

We are making an overhaul of the CLI so that we can automate the generation of templates for the frameworks that Storybook supports. The work also involves adding and improving E2E tests and making the storybook installation consistent across all frameworks.

This gives us the opportunity to:

General

There is already quite some work done, and it has been divided into multiple PRs.

Framework Task owner PR Status
Web Components @tooppaaa #10703 MERGED
Svelte @tooppaaa #10704 MERGED
HTML @tooppaaa #10705 MERGED
RAX @tooppaaa #10706 MERGED
Mithril @tooppaaa #10707 MERGED
Vue @tooppaaa #10708 MERGED
Webpack React @tooppaaa #10709 MERGED
React scripts @tooppaaa #10710 MERGED
React @tooppaaa #10711 MERGED
Preact @tooppaaa #10712 MERGED
Ember @tooppaaa #10713 MERGED
SFC Vue @tooppaaa #10714 MERGED
Riot @tooppaaa #10715 MERGED

Additional tasks

The table below will be updated as new tasks arise: Task Task owner PR Status
#10793 CLI: colocate example components together with generated stories @tooppaaa #10935 MERGED
#10794 CLI: consistent welcome-component in all generators @tooppaaa #11422 MERGED
#11282 CLI: use addon essentials in storybook templates @tooppaaa - MERGED
#10796 CLI: remove addon notes from framework generators @yannbf - CLOSED
#10797 CLI: Improve support of Yarn 2 in E2E tests @gaetanmaisse #10797 #11342 MERGED
#10798 CLI: check for missing/unneeded deps when initializing SB in a project - - CLOSED

Discussion

  1. Stories being generated under stories vs src/stories.

    • Currently it's inconsistent across frameworks. What's should be the correct path?

  2. Using demo components from @storybook/FRAMEWORK/demo vs shipping example components together with the stories.

    • Currently it's inconsistent across frameworks. Should we keep the stories boilerplate as minimal as possible by just importing components from the demos like React or should we ship example files like it's done with Vue?

  3. Updating Welcome component content.

    • The content of the Welcome component should be consistent across frameworks. One thing we noticed is the message about webpack: Have a look at the .storybook/webpack.config.js to add webpack loaders and plugins you are using in this project. although that file is not present. Maybe it should be just rephrased that if you add the file it will be picked up, or rather tell people to add the rules to main.js instead if that's the way to go. Also, in some frameworks there is inconsistency because in the welcome component there is a reference to stories/1-Button.stories.js but the correct path is actually src/stories/1-Button.stories.js and the other way around (to be aligned with point 1 above).

  4. removing notes parameter on template stories

    • Lots of example stories have notes as parameters, although the notes addon has been removed.

I'll be updating this text as we progress. For the ones working on this feel free to update this as well!

shilman commented 4 years ago

Thanks for opening this @yannbf! Agree with your suggestions across the board. The first question about stories vs src/stories is tricky.

Given this, perhaps we should:

WDYT?

ndelangen commented 4 years ago

Using demo components from @storybook/FRAMEWORK/demo vs shipping example components together with the stories.

agreed

add to src/stories if src exists, otherwise stories?

agreed

The content of the Welcome component should be consistent across frameworks. One thing we noticed is the message about webpack

We should update it so it mentions main.js and links to the docs.

yannbf commented 4 years ago

add to src/stories if src exists, otherwise stories?

Downside to this is we would need to change the implementation of the generators and make it more complex, because right now it just does a copySync of the entire template folder, very straight forward (but less dynamic).

Also, we'd need to change the text on the Welcome story based on that, because in that text there is a reference to one of the stories like this: Try editing the Button stories located at src/stories/1-Button.stories.js But of course if we revisit the content of the Welcome component we might not need to do that.

ndelangen commented 4 years ago

Downside to this is we would need to change the implementation of the generators and make it more complex

true, good point, that is a downside..

We could say we copy the stories into the project dir, then OPTIONALLY move the stories dir into the src directory?

And make sure the glob specified in main.js matches both.

Also, we'd need to change the text on the Welcome story based on that,

I think we can drop the src/ in that, because it's kinda obvious if the user already had a src directory we'd place it there.

tooppaaa commented 4 years ago

Here's my suggestion for the one-for-all wording of the introduction story. I took the react one as basis and tried to remain cross-framework, "src-independent", and provide useful links to the docs

Should we add a section that encourages the usage of docs ?

Welcome to storybook

This is a UI component dev environment for your app.

We've added some basic stories inside your source code.

A story is a single state of one or more UI components. You can have as many stories as you want.

(Basically a story is like a visual test case.)

Stories

You can add your own components as stories. Have a look at the Writing Stories section in our documentation.

Use the left panel to switch between stories.

Create new stories using one of the following format:

You can edit components and see changes right away.

(Try editing the Button stories located in the file called 1-Button.stories.js.)

Configuration

Your app may require additional configurations. Check our configuration documentation for more information

Tips

yannbf commented 4 years ago

So @shilman mentioned in one of the PRs:

Agree we should get rid of notes and pick a better example. Maybe backgrounds and/or docs?

What do we want to use? I think it would be nice to use docs because then eventually docs becomes part of storybook as a default experience and more people get to enjoy it out of the box!

tooppaaa commented 4 years ago

Docs is a different approach. I can see projects where I am not yet sure I'll install docs. (simpler is better). Same for backgrounds. So this leads to: Do we really need to demonstrate another addon in the CLI generator ?

This increase the maintenance cost (Lots of PR to harmonize only links & actions) In my opinion, the welcome page with links to addons and the button story does the job. We can later add a ref to a "discover storybook" instance using composition ? There will be a single place to maintain to add a demo of what storybook can do ?

Concerning @storybook/FRAMEWORK/demo I'm more in favor of colocating components & stories, mostly because that's what end users will have.

yannbf commented 4 years ago

Do we really need to demonstrate another addon in the CLI generator ?

That's a great question!

We can later add a ref to a "discover storybook" instance using composition ? There will be a single place to maintain to add a demo of what storybook can do ?

Sounds like a great idea!

shilman commented 4 years ago

@tooppaaa i think it's fine if the user has to delete some or even all of the code generated by the template -- that's already the case with stories. its main purposes are (1) to give users something useful out of the box and (2) to educate them about storybook concepts. what's nice specifically about the notes example is that it was both useful (prior to docs) and also demonstrated story parameters, which are a key concept in storybook.

ndelangen commented 4 years ago

it's fine if the user has to delete some or even all of the code generated by the template

But less is better.

referencing demo components from @storybook/<framework>/demo is better IMHO.

We can later add a ref to a "discover storybook" instance using composition ? There will be a single place to maintain to add a demo of what storybook can do

The issue is that (as @shilman mentions as well), that part of the purpose of this copied template is to give the user something to play with code-wise. If it's a ref they can see the storybook, but they cannot experience changing the component & story.

But I'm not apposed to the idea of adding a ref by default... WDYT? (asking to anyone reading this)

shilman commented 4 years ago

@yannbf @tooppaaa

In 5.3 I wrote a meta-addon called Storybook Essentials, which is a curated collection of zero-config addons for Storybook. I think Essentials should be the basis for the updated CLI template and related work.

Essentials had a technical limitation about package imports. However, I've fixed the limitation in in 6.0, and it's now available in https://github.com/storybookjs/storybook/pull/10737

Over the course of the 6.x milestones, we will actively promote essentials as the easiest way to get started with a high-quality Storybook experience. If all the CLI templates use it and all the tests make sure that it works smoothly with all the existing frameworks, it will be a huge win for users and for Storybook maintenance.

tooppaaa commented 4 years ago

Reusing what has been done ? Love the idea ! I didn't know about it but I've seen this experience in Apollo. You have a "simple" starter, with guidelines if you want to "eject". Is this ready to be used in CLI ?

shilman commented 4 years ago

Huzzah!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.0.0-beta.6 containing PR #10729 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.

yannbf commented 4 years ago

Hey @shilman what tasks based on this discussion do you think can be created so far? Or should we mature it a bit more before creating tasks?

shilman commented 4 years ago

@tooppaaa the updated essentials is now available as part of 6.0.0-beta.6. it's relatively untested, so i'm sure we'll find some issues, but hopefully nothing big.

@yannbf go for it! 💯

yannbf commented 4 years ago

Ok @shilman @ndelangen I'd love to create tasks however I'd like to know which ones should be tasks, which ones should not, and have a more concrete idea about them:

1 - Remove addon notes usage from CLI generated stories. 2 - Make CLI generated setup use only addon-essentials. Update E2E tests accordingly. 3 - Change the Welcome component content (please check the suggestion by @tooppaaa) and make it consistent in every template. 4 - From @ndelangen about sb init: We could say we copy the stories into the project dir, then OPTIONALLY move the stories dir into the src directory?

And this one doesn't seem to be decided 5 - Use demo components in generated stories OR 5 - Colocate components together with generated stories

If you could help me out shape these into proper tasks would be awesome!

ndelangen commented 4 years ago

my preferences: ✅ remove addon notes from generators ✅ add addon-essentials to the generators ❓ Use demo components in generated stories ❓ generate into the src directory if we can find one ✅ consistent welcome-component (and button) in all generators (let's show a pretty one, with:

@domyen would you be able to design a welcome-to-storybook component that can be re-used for all framework generators?

domyen commented 4 years ago

Sounds awesome Norbert, I can do that 👍

On Thu, May 14, 2020 at 8:59 AM Norbert de Langen notifications@github.com wrote:

my preferences: ✅ remove addon notes from generators ✅ add addon-essentials to the generators ❓ Use demo components in generated stories ❓ generate into the src directory if we can find one ✅ consistent welcome-component (and button) in all generators (let's show a pretty one, with:

  • storybook logo
  • link to storybook docs
  • link to discord invite
  • link to storybook repo on github
  • some message about the ability to add & write addons

@domyen https://github.com/domyen would you be able to design a welcome-to-storybook component that can be re-used for all framework generators?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/storybookjs/storybook/issues/10723#issuecomment-628617453, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACAJWKQNCTMIUOMHERHJGDRRPTLDANCNFSM4M5INNMA .

shilman commented 4 years ago

@yannbf @ndelangen we need to ship components with the stories. if we do:

it adds more complexity to the templates, but we just need to deal with it

yannbf commented 4 years ago

@gaetanmaisse would you be so kind and create issues about the following points you mentioned?

tooppaaa commented 4 years ago

@domyen Did you had a chance to work on that Welcome page ?

domyen commented 4 years ago

Hey @tooppaaa will work on that this coming week. I'm freed up some time to focus on SB design tasks. 👍

airtonix commented 4 years ago

Is this where we ask for the Progress spam to be turned off with a simple true statement in our main.js ? image

ndelangen commented 4 years ago

@airtonix yes, but that's really unrelated the the issue currently being discussed..

add --quiet to the start script

shilman commented 4 years ago

Jeepers creepers!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.0.0-rc.8 containing PR #11505 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.

ndelangen commented 4 years ago

@shilman can we close this issue?

maybe create a new issue to track the remaining bits if there are any?