For basics see How to contribute.
Styleguidist isn’t an ordinary single-page app and some design decisions may look confusing to an outsider. In this guide, we’ll explain these decisions to un-confuse potential contributors.
The main thing is that we’re running two apps at the same time: user’s components and Styleguidist UI. They share a webpack configuration and have styles in the same scope (there’s only one scope in CSS). And we can control only one of these two apps: Styleguidist UI. That puts us under some restrictions:
- Our styles should not affect user component styles.
- User styles (especially global like Bootstrap) should not affect Styleguidist UI.
font-family) should affect user components as the user expects but not Styleguidist UI.
How it works
Styleguidist uses react-docgen to parse source files (not transpiled). react-docgen finds exported React components and generates documentation based on PropTypes or Flow annotations.
Webpack loaders and webpack configuration
We use webpack loaders to hot reload the style guide on changes in user components, styles and Markdown documentation. We have three loaders (loaders folder):
styleguide-loader: loads components and sections;
props-loaders: loads props documentation using react-docgen;
examples-loader: loads examples from Markdown files;
Styleguidist tries to load and reuse the user’s webpack config (
webpack.config.js in project root folder). It works most of the time but has some restrictions: Styleguidist ignores some fields and plugins because they are already included (like
webpack.HotModuleReplacementPlugin), don’t make sense for a style guide (like
output) or may break Styleguidist (like
We’re trying to keep Styleguidist’s webpack config minimal to reduce clashes with the user’s configuration.
Most of StyleGuidist UI components consist of two parts:
Foo/Foo.js that contains all logic and
Foo/FooRenderer.js that contains all markup and styles. This allows users to customize rendering by overriding
*Renderer component using webpack aliases (or styleguideComponents config option):
All Styleguidist components should be imported like this:
import Foo from 'rsg-components/Foo' to make aliases work.
Each component folder usually has several files:
Foo/Foo.js(optional for basic components);
Foo/index.js— reexport of
For styles we use JSS, it allows users to customize their style guide and allows us to ensure style isolation (thanks to jss-isolate). No user styles should affect Styleguidist UI and no Styleguidist styles should affect user components.
Use clsx to merge several class names or for conditional class names, import it as
import cx from 'clsx').
Check available theme variables in src/client/styles/theme.js.
Because of isolation and theming you need to explicitly declare
isolate: false to your hover styles, otherwise you’ll have to repeat base non-hover styles.
We’re using Jest with Enzyme for testing. Put your component tests into
Component.spec.js file in the same folder and all other tests into
To test particular class names use
classes function (available in the global namespace in tests):