- Use the
2.x
versions for babel 5,3.x
for babel 6.' - Note that babel 6.4 requires semicolons in your class properties standard/standard#372; packages have been fixed to 6.3 for now due to conflicts with using `standard.
- PRs are welcome, feel free to contribute to the project!
A React component guide that generates code examples, prop documentation, rendered component samples and is built for active development.
- Renders out components that can be interacted with
- Uses
webpack
+ hot module replacement to automatically update the guide as you work on your components react-docgen
is used under the hood to document your component'spropTypes
- Can manually + automatically generate code samples w/ syntax highlighting
Demo using the React-Bootstrap.
This project is originally forked from react-styleguide-generator.
Differences:
- Removed
browserify
and replaced withwebpack
+ hot module replacement - Complete overhaul of the core
rsg.js
lib to supportwebpack
react-docgen
generation and asset distribution moved to custom webpack plugins- Fixed a bug where using input text boxes and typing into them will shift focus to the search box
- Improved highlighting performance - extremely large guides should not take forever to render
- Config file can now be an exported object, allowing for more dynamic configuration
See HISTORY.md
for future update info
- React 0.14.x. Install both
react
andreact-dom
. - Was developed on node 4 w/ npm 3.4. Unsure if older node versions work or not.
npm install rsg-alt
NOTE: By default Babel's static
keyword is disabled. You can turn them on individually by passing stage 0
as a babelrc or options.babelConfig.
Create file for the styleguide, and then add some documentation to a static field named styleguide
. You can use the ES6 syntax by Babel.
import React from 'react'
import Button from './Button'
export default class extends React.Component {
static styleguide = {
index: '1.1',
category: 'Elements',
title: 'Button',
description: 'You can use **Markdown** within this `description` field.',
code: `<Button size='small|large' onClick={Function}>Cool Button</Button>`,
className: 'apply the css class'
}
onClick () {
alert('Alo!')
}
render () {
return (
<Button size='large' onClick={this.onClick}>Cool Button</Button>
)
}
}
index
: Reference to the element's position in the styleguide (optional)category
: Components category nametitle
: Components titledescription
: Components description (optional)code
: Code example (optional). Not specifying this will not auto-generate an example.className
: CSS class name (optional)
Additional examples in tabs (optional) Demo
You can optionally use tabs to segment out examples for a component:
import React from 'react'
import Button from './Button'
export default class extends React.Component {
static styleguide = {
…
// Component to use for generating additional examples
exampleComponent: Button,
// Array of additional example tabs
examples: [{
tabTitle: 'Default',
props: {
children: 'Default'
}
}, {
tabTitle: 'Primary',
props: {
kind: 'primary',
children: 'Primary',
onClick () {
alert('o hay!')
}
}
}]
}
}
exampleComponent
:ReactElement
to use to generate the examples.examples
: Array of examples, which generates additional tabs of example components and sample codeexamples[].tabTitle
: Title of example tabexamples[].props
: Properties to assign to the rendered example componentexamples[].props.children
: (optional) Child elements to assign to the example componentexamples[].code
: (optional) Code example. Omitting this will attempt to auto-generate a code example using theexamples[].props
Additional examples via doc comment (optional) Demo
Doc comment support example is:
/**
* Substitute this description for `styleguide.description`.
*/
export default class extends Component {
// required for prop documentation
static displayName = 'ExampleButton'
static styleguide = {
…
}
// Document the props via react-docgen
static propTypes = {
/**
* Block level
*/
block: React.PropTypes.bool,
/**
* Style types
*/
kind: React.PropTypes.oneOf(['default', 'primary', 'success', 'info'])
}
render () {
return <Button block kind='primary'>Cool Button</Button>
}
}
If necessary, visit react-styleguide-generator-alt/example to see more complete examples for the documenting syntax.
A common usage example is below.
# The default output to `styleguide` directory
rsg 'example/**/*.js'
Type rsg -h
or rsg --help
to get all the available options.
Usage: rsg [input] [options]
Options:
-o, --output Output directory ['styleguide']
-t, --title Used as a page title ['Style Guide']
-r, --root Set the root path ['.']
-f, --files Inject references to files ['']
-c, --config Use a js/json config file ['styleguide.json']
-p, --pushstate Enable HTML5 pushState [false]
-v, --verbose Verbose output [false]
-d, --dev Start server with webpack hmr [3000]
Examples:
rsg 'example/**/*.js' -t 'Great Style Guide' -f 'a.css, a.js' -v
# Necessary to use a config file if you want to enable react-docgen
rsg 'example/**/*.js' -c 'styleguide.json' -v
# Example 2 - config file does module.exports = { ... }
rsg 'example/**/*.js' -c 'styleguide.js' -v
var gulp = require('gulp')
var RSG = require('rsg-alt')
gulp.task('styleguide', function (done) {
var rsg = RSG('example/**/*.js', {
output: 'path/to/dir',
files: ['a.css', 'a.js']
})
rsg.generate(function (err) {
if (err) {
console.error(String(err))
}
done()
})
})
var RSG = require('rsg-alt')
grunt.registerTask('rsg', 'React style guide', function () {
var done = this.async()
try {
var conf = grunt.config.get('rsg')
RSG(conf.input, {
config: conf.configFile,
dev: false,
verbose: true
}).generate(function (err) {
if (err) {
grunt.log.error('Error: ' + err + ' ' + err.stack())
return done(false)
}
grunt.log.ok('react styleguide generation complete')
done()
})
} catch (e) {
grunt.log.error('Error: ' + e + ' ' + e.stack)
done(false)
}
})
Returns a new RSG instance.
Type: String
Refers to glob syntax or it can be a direct file path.
Type: String
Default: 'styleguide'
Output directory path.
Type: String
Default: 'Style Guide'
Used as a page title and in the page header.
Type: Array
Default: input
An array of glob
-able file/paths for react-docgen
to parse. If not specified, will default the value to input
.
Type: String
Default: '.'
Set the root path. For example, if the styleguide is hosted at http://example.com/styleguide
the options.root
should be styleguide
.
Type: Array
Default: null
Inject references to files. A usage example is:
{
files: [
'//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css',
'a.css',
'a.js',
'icon.svg'
]
}
Check for the existence of the files and only copy the files if it exists.
styleguide/files
├─ a.css
├─ a.js
└─ icon.svg
Inject file references into index.html if the files with the extension .css
or .js
.
<!doctype html>
<html>
<head>
…
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
<link rel="stylesheet" href="files/a.css">
</head>
<body>
…
<script src="files/a.js"></script>
</body>
</html>
Type: String|Object
Default: styleguide.json
The entire range of RSG API options is allowed. Usage example.
- An object can be passed instead of a filename that contains the RSG API options.
- A Javascript file can be passed in that exports an object instead:
// styleguide.js
module.exports = {
"title": "React Style Guide",
"files": [
"//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css",
"example/example.css"
],
"babelConfig": {
"stage": 0
},
"webpackConfig": {}
}
Type: String
Default: false
Enable HTML5 pushState. When this option is enabled, styleguide will use history API.
Type: Object
Default: null
A usage example is below. See the babel docs for the complete list.
{
babelConfig: {
stage: 0
}
}
Type: Object
Default: {}
Uses deepmerge
to merge in a custom webpack configuation to the rsg webpack configuration. Existing arrays (eg plugins) are appended to maintain functionality.
Type: Array<String|RegExp>
Default: null
Adds a custom rule(s) to the webpack loader to include additional items to transpile via babel-loader
. This is provided as a convenience to using webpackConfig
directly.
Generate the files and their dependencies into a styleguide output.
Get the demo running locally:
git clone git@github.com:theogravity/react-styleguide-generator-alt.git
cd react-styleguide-generator-alt/example/
npm install
npm start
Visit http://localhost:3000/ in your browser.
Make sure your component contains displayName
and render()
.