Simplify setup AKA 5.0.0

[sapegin]

Work in the next branch

Difficult first-time configuration is a known issue that we really want to solve. Here are some ideas for the next major release that might help:

• CSS Modules → jss — simplify styling — [RFC] CSS Modules → JSS #207.
• Easier Webpack configuration — Simplify Webpack configuration #221.
• Compile Styleguidist’s code to ES5 — get rid of babel-loader.
• Ret rid of most Webpack loaders except JSON loader.
• Add default JSON loader for npm modules when needed.
• Remove include/exclude option requirement for loaders.
• Remove global Lodash, add context option — Remove general lodash require? #249
• Default / base Webpack config — Default / base Webpack config #222.
• User Webpack config auto discovery — User Webpack config auto discovery #255

Postponed:

• CLI configuration tool (maybe) — CLI for simpler project setup #208.

Anything else? Any feedback?

/cc @okonet, @varya (as you have fresh experience ;–)

[okonet]

Ideally for webpack users it should not require editing project's webpack config and work like storybook (takes your webpack config but allows to extend it). Even better would be just a plugin for webpack. In this setup is really a breeze: https://github.com/carteb/carte-blanche#setup

I can't speak a lot for non-webpack users but sane defaults sound good to me.

Styleguidist own code should definitively be compiled since it is also will increase build speed I think. Also, distributing it is much easier then it's browser ready. Not sure why css-modules is a problem here. You still can generate a separate CSS bundle and provide it along with the index.html and main.js. But it would be interesting to see what advantages JSS can give here and theming sounds very good.

I don't think CLI tool will help a lot, but it might be a nice addition. Good example is create-react-app.

[sapegin]

Webpack plugin: I’m sure it’s possible to make a Webpack plugin for Styleguidist too. But I don’t think it should be the primary way of using Styleguidist. There are so many projects without Webpack (like component libraries or separate components). So it’s far from ideal but definitely nice to have.

Storybook: it sounds great except they don’t do that. They have default create-react-app-like config that works only when you don’t have any custom config. Otherwise it’s not different from what we have now.

CSS: yeah, the main benefit is easier theming. Plus no need for CSS loader (one of them) — less possible conflicts with user’s loaders (same benefit for compiling JS).

CLI: I hope it would make initial setup simpler and less scary. And looks great in docs and on site (which I want to make after this).

[aaronjensen]

There are so many projects without Webpack (like component libraries or separate components). So it’s far from ideal but definitely nice to have.

I could see styleguidist being multiple packages--core, which would be usable via webpack plugin or via cli.

[sapegin]

CLI (I mean config CLI, not the one we have now) will be a separate package that you install globally anyway.

[oliverturner]

Re styling, what are your thoughts on using a web component approach (with fallbacks) to improve isolation of Styleguidist components from Project components?

[sapegin]

How is this better than JSS? Especially if they aren’t supported almost anywhere.

[oliverturner]

Because the Styleguidist components won't be interfered with by global styles set from an imported stylesheet

[sapegin]

Same for JSS with jss-isolate but I don’t see any benefits ;-|

[oliverturner]

The project I'm working on sets a bunch of styles on bare elements - h1-6, p, a, etc. - this wreaks havoc with Styleguidist

[sapegin]

We can use divs and spans with the same effect but without need for any polyfills.

[okonet]

I believe if you use something like initial: all you can avoid this. AFAIK JSS-isolate should solve that as well. @kof can you comment on this?

[sapegin]

That’s why I like JSS here: it solve multiple problems.

[kof]

Yes, the idea behind jss-isolate is exactly this. Also we are thinking of adding an option for shadow-dom like isolation

[sapegin]

Looks like it’ll be better than I thought ;-)

[n1313]

Not sure if this is the right place to do this, but anyway: may I suggest adding an option to build docs with --progress enabled? Or adding a note to the documentation on how to pass arguments to Webpack from CLI. I can't figure it out.

[sapegin]

@n1313 We don’t use CLI, but you can try progress-bar-webpack-plugin — maybe we should add it by default if it‘s good.

[n1313]

By saying "from CLI" I mean running styleguidist server --config ./styleguidist.config.js. It doesn't have to be a fancy plugin, Webpack's native --progress is good enough. Being able to turn this on from the config would be sweet.

[sapegin]

@n1313 Styleguidist CLI uses Webpack Node.js and --progress option is only available on CLI as I understand. So the plugin is the only option.

[n1313]

Oh, I see, you were talking about Webpack CLI, not Styleguidist CLI. Right. I will look into the plugin then. Thanks!

[tizmagik]

Migration docs? Or will it be easy to upgrade from v4? Sorry if I missed another issue that addresses this already!

[sapegin]

@tizmagik I have a change log draft so far. There are some migration notes. Let me know if I need to write more.

[n1313]

@sapegin, I think what most users would like to know is answers to "why should I update" and "what do I need to change in my project if I decide to update" questions. It would be great is these points could be highlighted in the release notes.

[sapegin]

@n1313 I’ve tried to answer both questions. Let me know if anything is missing.

[iamstarkov]

yo, @sapegin, is there any release/changelog notes for v5-beta? 5.0.0-beta8 is available through npm, but i struggle to try it out wo/ aforementioned notes or/and migration path. can you help?

[sapegin]

@iamstarkov Yo! There’s a change log draft with migration notes and all braking changes. Let me know if I miss something. And I appreciate any feedback! ;-)

[sapegin]

The official beta is here. Please try it if you have some time ;-)

https://github.com/styleguidist/react-styleguidist/releases/tag/5.0.0%40beta.9

[tizmagik]

Exciting!! 😁

[sapegin]

5.0.0 is out!!