rosko / react-styleguidist

React style guide generator

React Styleguidist

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.

Installation

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.

1. Install from npm:

   npm install --save-dev react-styleguidist

2. 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.

4. 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 to development and when you build style guide NODE_ENV is set to production. You can use this fact to enable HMR only in development. So update your .babelrc:

   {
     "presets": ["es2015", "react"],
     "env": {
       "development": {
         "presets": ["react-hmre"]
       }
     }
   }

5. Add these scripts to your package.json:

{
  // ...
  "scripts": {
    "styleguide-server": "styleguidist server",
    "styleguide-build": "styleguidist build"
  }
}

6. Run npm run styleguide-server to start style guide dev server.

To customize your style guide, head to the Configuration section below.

Documenting components

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 the getExampleFilename option.

  React component example:
  
      <Button size="large">Push Me</Button>
  
  Any [Markdown](http://daringfireball.net/projects/markdown/) is **allowed** _here_.

• Loading examples using doclet tags

  Additional example files can be specifically associated with components using doclet (@example) syntax. The following component will also have an example as loaded from the extra.examples.md file.

  /**
   * Component is described here.
   *
   * @example ./extra.examples.md
   */
  export default class SomeComponent extends React.Component {
    // ...
  }

Writing code examples

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.

Configuration

You can change some settings in the styleguide.config.js file in your project’s root folder.

• components
  Type: String or Function, required unless sections is provided
  

  • 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 or components/Button/Button.js or components/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);
      });
    }
  };

• sections
  Type: Array

  Allows components to be grouped into sections with a title and optional overview content. Sections can also be content only, with no associated components (for example, a textual introduction). A section definition consists of:
  

  • name - the title of the section.
  • content (optional) - location of a Markdown file containing the overview content.
  • components (optional) - a string or function providing a list of components. The same rules apply as for the root components option.

  Configuring a guide with a textual introduction section, then a UI section would look like:

  module.exports = {
    // ...
    sections: [
      {name: 'Introduction', content: 'docs/introduction.md'},
      {name: 'UI Components', content: 'docs/ui.md', components: 'lib/components/ui/*.js'}
    ]
  }

• skipComponentsWithoutExample
  Type: Boolean, default: false
  When set to true, ignore components that don't have an example file (as determined by getExampleFilename).

• styleguideDir
  Type: String, default: styleguide
  Folder for static HTML style guide generated with styleguidist 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: finds Readme.md in the component folder
  Function that returns examples file path for a given component path.

  For example, instead of Readme.md you can use ComponentName.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 print import 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;
    }
  };

• propsParser
  Type: Function, optional
  Function that allows you to override the mechanism used to parse props from a source file. Default mechanism is using react-docgen to parse props.

  module.exports = {
    // ...
    propsParser: function(filePath, source) {
      return require('react-docgen').parse(source);
    }
  }

• resolver
  Type: Function, optional
  Function that allows you to override the mechanism used to identify classes/components to analyze. Default behaviour is to find a single exported component in each file (and failing if more than one export is found). Other behaviours can be configured, such as finding all components or writing a custom detection method. See the react-docgen resolver documentation for more information about resolvers.

  module.exports = {
    // ...
    resolver: require('react-docgen').resolver.findAllComponentDefinitions
  }

• handlers
  Type: Array of Function, optional
  Array of functions used to process the discovered components and generate documentation objects. Default behaviours include discovering component documentation blocks, prop types and defaults. If setting this property, it is best to build from the default react-docgen handler list, such as in the example below. See the react-docgen handler documentation for more information about handlers.

  module.exports = {
    // ...
    handlers: require('react-docgen').defaultHandlers.concat(function(documentation, path) {
      // Calculate a display name for components based upon the declared class name.
      if (path.value.type == 'ClassDeclaration' && path.value.id.type == 'Identifier') {
        documentation.set('displayName', path.value.id.name);
  
        // Calculate the key required to find the component in the module exports
        if (path.parentPath.value.type == 'ExportNamedDeclaration') {
          documentation.set('path', path.value.id.name);
        }
      }
  
      // The component is the default export
      if (path.parentPath.value.type == 'ExportDefaultDeclaration') {
        documentation.set('path', 'default');
      }
    }))
  }

CLI commands and options

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.

FAQ

How to add custom JS and CSS?

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.

How to change styles of a style guide?

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.

How to change the behaviour of a style guide?

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>
    );
  }
}

How to debug my components and examples?

1. Open your browser’s developer tools
2. Write debugger; statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.

How to debug the exceptions thrown from my components?

1. Put debugger; statement at the beginning of your code.
2. Press the button in your browser’s developer tools.
3. Press the button and the debugger will stop execution at the next exception.

Why does the style guide list one of my prop types as unknown?

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'
};

Similar projects

• 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.

Changelog

The changelog can be found on the Releases page.

Contributing

Everyone is welcome to contribute. Please take a moment to review the contributing guidelines.

Author and License

Artem Sapegin and contributors.

MIT License, see the included License.md file.