React Styleguidist Integration Plugin for SourceJS


Fork of React Style Guide generator react-styleguidist with integration to SourceJS platform.

Original styleguidist example.
(example with SourceJS will be available later)


To add automatically generated React props docs use sourcejs-react-docgen plugin. Check SourceJS React bundle example for more insights.

Installation

``
cd sourcejs-project
npm install sourcejs-react-styleguidist --save
`

Add custom markdown renderer conf into SourceJS options.js file:

`javascript
module.exports = {
core: {
processMd: {
languageRenderers: {
jsx: require('sourcejs-react-styleguidist/core/lang-jsx').processExample
}
}
}
};
`

After re-running your SourceJS app, plugin will be loaded automatically.

$3

Configure path to components in SourceJS options.js file:

`javascript
module.exports = {
plugins: {
reactStyleguidist: {
rootDir: './relative/path/to/components',
components: './*/.jsx'
}
}
};
`

See Configuration section below for the list of available options.

Documenting components

Examples are written in Markdown where any code blocks will be rendered as a react components. 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:

`jsx
Push Me
`

Any Markdown:

* Foo;
* bar;
* baz.

How it works

SourceJS plugins are loaded together with main application, adding additional initialization steps or changing rendering flow using middleware integration. With this plugin, in development mode, SourceJS in enhanced with webpack middleware, that builds all the React examples on demand and listens to file changes for hot-reloading.

In production mode webpack is not triggered, expecting that bundle is already built (read configuration section for more).

Rendering flow with this plugins looks like this:

* On app start webpack-dev-middleware and webpack-hot-middleware are loaded from core/index.js
* Then happens initial build of bundle.js which packs all the components and development tools into one package
* Using custom loaders, webpack gathers info about all component from readme.md files, and saves defined code examples
* On Spec page request, common bundle.js is loaded onto every page, loading only examples of defined spec
* To determine which component to load from common bundle, all examples are grouped by Spec name, and special middleware (code/middleware/index.js) during rendering flow replaces code examples from readme.md with special hooks, that are then used as roots to React components
* Using SourceJS as a platform together with this integration plugin you get benefits both from SourceJS ecosystem, and custom client-side rendreding handled by react/webpack and hot module replacement tool

Configuration

Use SourceJS options.js for deep plugin configuration.

* enabled
Type: Boolean
Set to false, if wan't to disable plugin load with SourceJS app.

* preBuild
Type: Boolean
Set to true, if you wan't to automatically build webpack bundle in production mode right after app starts.

* rootDir
Type: String, required
Your components sources root folder (eg. ./lib). Should not point to a folder with the node_modules folder.

* components
Type: String or Function, required
- when String: a glob pattern that matches all your component modules. Relative to the rootDir.
- when Function: function that returns an array of modules.

If your components look like components/Button.jsx or components/Button/Button.jsx or components/Button/index.jsx:

`javascript
components: './components/*/.jsx'
`

If your components look like components/Button/Button.js + components/Button/index.js:

`javascript
components: function(config, glob) {
return glob.sync(config.rootDir + '/components/*/.js').filter(function(module) {
return /\/[A-Z][a-z]*\.js$/.test(module);
});
},
`

* 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:

`javascript
getExampleFilename: function(componentpath) {
return componentpath.replace(/\.jsx?$/, '.examples.md');
}
`

* updateWebpackConfig
Type: Function, optional
Function that allows you to modify Webpack config for style guide:

`javascript
updateWebpackConfig: function(webpackConfig, env) {
if (env === 'development') {
/ ... modify config ... /
}
return webpackConfig;
}
`

$3

Running app with NODE_ENV=production, initial webpack build won't be triggered. To properly prepare production environment, first run react-styleguidist build command, and only after that run application:

`
NODE_ENV=production node ./node_modules/sourcejs-react-styleguidist/core/build.js
NODE_ENV=production npm start
`

Note: this command should be ran from SourceJS root folder, where node_modules is placed.

Alternatively, you can set preBuild` to true in plugin configuration, to build webpack bundle once app is ran in production mode. This will require less build steps, but may cause higher load in production environment container.

Contributing

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

---

License

The MIT License, see the included license.md file.