React Styleguidist is a style guide generator for React components. It lists component propTypes
and shows live, editable usage examples based on Markdown files. You can use it to generate a static HTML page to share and publish or as a workbench for developing new components using hot reloaded dev server. Check out the demo style guide.
Based on Webpack, webpack-dev-server and Babel.
Requirements: Only Babel 6 is supported in Styleguidist 2.0.0+. If you don't use Babel in your project, that's fine, but if you use Babel 5, please use Styleguidist 1.3.2. Webpack is recommended, but not required.
-
Install from npm:
npm install --save-dev react-styleguidist
-
Add a
styleguide.config.js
file into your project’s root folder. A simplest possible config looks like this:module.exports = { title: 'My Great Style Guide', components: './lib/components/**/*.js', // Put other configuration options here... };
3. If you use transpilers to run your project files (JSX → JS, SCSS → CSS, etc), you need to set them up for the style guide too.
Styleguidist generates a webpack config that contains all that is needed for the style guide, but you need to configure the [webpack loaders](https://webpack.github.io/docs/configuration.html#module-loaders) for your project code.
Put the `updateWebpackConfig` function in your `styleguide.config.js`:
```javascript
var path = require('path');
module.exports = {
updateWebpackConfig: function(webpackConfig, env) {
// Your source files folder or array of folders, should not include node_modules
let dir = path.join(__dirname, 'src');
webpackConfig.module.loaders.push(
// Babel loader will use your project’s .babelrc
{
test: /\.jsx?$/,
include: dir,
loader: 'babel'
},
// Other loaders that is needed for your components
{
test: /\.css$/,
include: dir,
loader: 'style!css?modules&importLoaders=1'
}
);
return webpackConfig;
},
};
Note: don’t forget include
or exclude
options for your Webpack loaders, otherwise they will interfere with Styleguidist’s loaders. Also do not include node_modules
folder.
-
Configure React Transform HMR (hot module replacement). This is optional, but highly recommended.
Install React Transform for Babel (if you don't have it yet):
npm install --save-dev babel-preset-react-hmre
.When you run the styleguidist server,
NODE_ENV
is set todevelopment
and when you build style guideNODE_ENV
is set toproduction
. You can use this fact to enable HMR only in development. So update your.babelrc
:{ "presets": ["es2015", "react"], "env": { "development": { "presets": ["react-hmre"] } } }
-
Add these scripts to your
package.json
:
{
// ...
"scripts": {
"styleguide-server": "styleguidist server",
"styleguide-build": "styleguidist build"
}
}
- Run
npm run styleguide-server
to start style guide dev server.
To customize your style guide, head to the Configuration section below.
Styleguidist generates documentation from 2 sources:
-
PropTypes and component description in the source code
Components'
PropTypes
and documentation comments are parsed by the react-docgen library. Have a look at their example of a component documentation. -
Usage examples and further documentation in Markdown
Examples are written in Markdown where any code block without a tag will be rendered as a react component. By default any
Readme.md
in the component folder is treated as an examples file but you can change it with thegetExampleFilename
option.React component example: <Button size="large">Push Me</Button> Any [Markdown](http://daringfireball.net/projects/markdown/) is **allowed** _here_.
Code examples in Markdown use the ES6+JSX syntax. They can access all the components listed, they are exposed as global variables.
You can also require
other modules (e.g. mock data that you use in your unit tests) from examples in Markdown:
const mockData = require('./mocks');
<Message content={mockData.hello}/>
As an utility, also the lodash library is available globally as _
.
Each example has its own state that you can access at the state
variable and change with the setState
function. Default state is {}
.
<div>
<button onClick={() => setState({isOpen: true})}>Open</button>
<Modal isOpen={state.isOpen}>
<h1>Hallo!</h1>
<button onClick={() => setState({isOpen: false})}>Close</button>
</Modal>
</div>
If you want to set the default state you can do:
'key' in state || setState({key: 42});
You can use React.createClass
in your code examples, but if you need a more complex demo it’s often a good idea to define it in a separate JavaScript file instead and then just require
it in Markdown.
You can change some settings in the styleguide.config.js
file in your project’s root folder.
-
components
Type:String
orFunction
, required- when
String
: a glob pattern that matches all your component modules. Relative to config folder. - when
Function
: a function that returns an array of module paths.
If your components look like
components/Button.js
orcomponents/Button/Button.js
orcomponents/Button/index.js
:components: './components/**/*.js',
If your components look like
components/Button/Button.js
+components/Button/index.js
:var path = require('path'); var glob = require('glob'); module.exports = { // ... components: function() { return glob.sync(path.resolve(__dirname, 'lib/components/**/*.js')).filter(function(module) { return /\/[A-Z]\w*\.js$/.test(module); }); } };
- when
-
skipComponentsWithoutExample
Type:Boolean
, default:false
When set totrue
, ignore components that don't have an example file (as determined bygetExampleFilename
). -
styleguideDir
Type:String
, default:styleguide
Folder for static HTML style guide generated withstyleguidist build
command. -
assetsDir
Type:String
, optional
Your application static assets folder, will be accessible as/
in the style guide dev-server. -
template
Type:String
, default: src/templates/index.html
HTML file to use as the template for the output. -
title
Type:String
, default:Style guide
Style guide title. -
serverHost
Type:String
, default:localhost
Dev server host name. -
serverPort
Type:Number
, default:3000
Dev server port. -
highlightTheme
Type:String
, default:base16-light
CodeMirror theme name to use for syntax highlighting in examples. -
getExampleFilename
Type:Function
, default: findsReadme.md
in the component folder
Function that returns examples file path for a given component path.For example, instead of
Readme.md
you can useComponentName.examples.md
:module.exports = { // ... getExampleFilename: function(componentpath) { return componentpath.replace(/\.jsx?$/, '.examples.md'); } };
-
getComponentPathLine
Type:Function
, default: optional
Function that returns a component path line (displayed under the component name).For example, instead of
components/Button/Button.js
you can printimport Button from 'components/Button';
:var path = require('path'); module.exports = { // ... getComponentPathLine: function(componentPath) { var name = path.basename(componentPath, '.js'); var dir = path.dirname(componentPath); return 'import ' + name + ' from \'' + dir + '\';'; } };
-
updateWebpackConfig
Type:Function
, optional
Function that allows you to modify Webpack config for style guide:module.exports = { // ... updateWebpackConfig: function(webpackConfig, env) { if (env === 'development') { // Modify config... } return webpackConfig; } };
These commands supposed to be placed in package.json
scripts
(see Installation section above). If you want to run them directly, use ./node_modules/.bin/styleguidist
.
styleguidist server
: Run dev server.
styleguidist build
: Generate a static HTML style guide.
CLI Options:
--config <file>
: Specify path to the config file.--verbose
: Print debug information.
Add a new Webpack entry point. In your style guide config:
var path = require('path');
module.exports = {
// ...
updateWebpackConfig: function(webpackConfig, env) {
webpackConfig.entry.push(path.join(__dirname, 'path/to/script.js'));
webpackConfig.entry.push(path.join(__dirname, 'path/to/styles.css'));
return webpackConfig;
}
};
You may need an appropriate Webpack loader to handle these files.
Add a new Webpack entry point in your style guide config:
var path = require('path');
module.exports = {
// ...
updateWebpackConfig: function(webpackConfig, env) {
webpackConfig.entry.push(path.join(__dirname, 'lib/styleguide/styles.css'));
return webpackConfig;
}
};
Now you can change almost any piece of a style guide. For example you can change a font and a background color:
.ReactStyleguidist-common__font {
font-family: "Comic Sans MS", "Comic Sans", cursive;
}
.ReactStyleguidist-colors__base-bg {
background: hotpink;
}
Use your browser’s developer tools to find CSS class names of the elements you want to change.
You can replace any Styleguidist React component. In your style guide config:
var path = require('path');
module.exports = {
// ...
updateWebpackConfig: function(webpackConfig, env) {
webpackConfig.resolve.alias['rsg-components/StyleGuide'] = path.join(__dirname, 'lib/styleguide/StyleGuide');
return webpackConfig;
}
};
Also there are two special wrapper components. They do nothing by themselves and were made specifically to be replaced with a custom logic:
StyleGuide
— the root component of a style guide React app.Wrapper
— wraps every example component.
For example you can replace the Wrapper
component to wrap any example in the React Intl’s provider component. You can’t wrap the whole style guide because every example is compiled separately in a browser.
// styleguide.config.js
var path = require('path');
module.exports = {
// ...
updateWebpackConfig: function(webpackConfig, env) {
webpackConfig.resolve.alias['rsg-components/Wrapper'] = path.join(__dirname, 'lib/styleguide/Wrapper');
return webpackConfig;
}
};
// lib/styleguide/Wrapper.js
import React, { Component } from 'react';
import { IntlProvider } from 'react-intl';
export default class Wrapper extends Component {
render() {
return (
<IntlProvider locale="en">
{this.props.children}
</IntlProvider>
);
}
}
- Open your browser’s developer tools
- Write
debugger;
statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.
- Put
debugger;
statement at the beginning of your code. - Press the
button in your browser’s developer tools.
- Press the
button and the debugger will stop exception a the next exception.
This occurs when you are assigning props via getDefaultProps
that are not listed within the components propTypes
.
For example, the color prop here is assigned via getDefaultProps
but missing from the propTypes
, therefore the style guide is unable to display the correct prop type.
Button.propTypes = {
children: PropTypes.string.isRequired,
size: PropTypes.oneOf(['small', 'normal', 'large']),
};
Button.defaultProps = {
color: '#333',
size: 'normal'
};
- React Styleguide Generator, a React style guide generator.
- heatpack, a quick to setup hot-reloaded development server for React components.
- Demobox, a component for making component showcases for landing pages.
- React-demo, a component for creating demos of other components with props editor.
- Atellier, a React components emulator.
- Cosmos, a tool for designing truly encapsulated React components.
- SourceJS, a platform to unify all your frontend documentation. It has a Styleguidist plugin.
The changelog can be found on the Releases page.
Everyone is welcome to contribute. Please take a moment to review the contributing guidelines.
Artem Sapegin and contributors.
MIT License, see the included License.md file.