`react-component-illustrator` takes in a list of examples for your library of [React.js](https://facebook.github.io/react/) components, group them by the component they are showcasing (you may have more than one example for a component), and return an arr
npm install react-component-illustratorreact-component-illustrator takes in a list of examples for your library of React.js components, group them by the component they are showcasing (you may have more than one example for a component), and return an array of illustrations of your components, along with their examples.
npm install --save-dev react-component-illustrator
The input of your resulting illustration comes from your React.js components and the examples.
For the most part, you just develop/document them like you normally would (using comment blocks in your .js files), with a few opinionated behaviors I throw in. Here's an example:
Consider you have a project structure like so:
``
AwesomeComponents
├── src
│ └── components
│ ├── Button
│ │ ├── Button.js
│ │ └── examples
│ │ ├── SimpleButton.js
│ │ ├── AnotherButton.js
│ │ └── IconButton.js
│ └── ...
└── ...
And your file contents:
`
// src/components/Button/Button.js
import React, { PropTypes, Component } from 'react';
/**
* Some description for Button
*
* some more description for Button
*/
export default class Button extends Component {
static propTypes = {
/**
* Property string's description
*/
string: PropTypes.string,
required: PropTypes.any.isRequired,
instanceOf: PropTypes.instanceOf(MyPropType),
customProp: function (props, propName, componentName) {
if (!/My/.test(props[propName])) {
return new Error('Invalid customProp');
}
}
};
render() {
return (
);
}
}
`
##### Note:
You can add docs for each propTypes by adding / */ comment blocks
`
// src/components/Button/examples/SimpleButton.js
import React, { Component } from 'react';
import Button from '../Buton';
/**
* SimpleButton
* description
*
* @name SimpleButtonExample
* @component ../../Button
*/
export default class SimpleButtonExample extends Component {
render() {
let foo =
return (
##### Note:
* You can use
in jsDoc tag style to customize the name of your example in the output, without it, the name of your example's class would be returned.
* You NEED to use a @component tag in your documentation of the example to associate your example with a particular component that you are showcasing. Without this, your example would be categorized under "Random Examples".`
// src/components/Button/examples/AnotherButton.js
import React, { Component } from 'react';
import Button from '../Buton';export default class AnotherButtonExample extends Component {
render() {
return (
// src/components/Button/examples/IconButton.js
import React, { Component } from 'react';
import Button from '../Buton';/**
* IconButtonExample
*
* @component ../../Button
*/
export default class IconButtonExample extends Component {
render() {
let foo =
Icon; return (
{foo}
);
}
}
$3
Running
logges the following (modified/beautified for ease of reading)`
module.exports = [
{
"name": "Button",
"path": "path/to/.../src/components/Button/Button.js",
"source": "... source code of src/components/Button/Button.js (as string)",
"description": "Some description for Button\n\nsome more description for Button",
"props": {
"string": {
"type": {
"name": "string"
},
"required": false,
"description": "Property string's description"
},
"required": {
"type": {
"name": "any"
},
"required": true,
"description": ""
},
"instanceOf": {
"type": {
"name": "instanceOf",
"value": "MyPropType"
},
"required": false,
"description": ""
},
"customProp": {
"type": {
"name": "custom",
"raw": "function (props, propName, componentName) {\n if (!/My/.test(props[propName])) {\n return new Error('Invalid customProp');\n }\n}"
},
"required": false,
"description": ""
}
},
"examples": [
{
"name": "SimpleButton",
"path": "path/to/.../src/components/Button/examples/SimpleButton.js",
"renderer": require("./src/components/Button/examples/SimpleButton.js"),
"requirePath": "./src/components/Button/examples/SimpleButton.js",
"description": "SimpleButtonExample
description
",
"source": "... source code of src/components/Button/examples/SimpleButton.js (as string)",
"renderSource": "render() {\n let foo = ;\n return \n {foo}\n \n ;\n}"
},
{
"name": "IconButtonExample",
"path": "path/to/.../src/components/Button/examples/IconButton.js",
"renderer": require("./src/components/Button/examples/IconButton.js"),
"requirePath": "./src/components/Button/examples/IconButton.js",
"description": "IconButtonExample
",
"source": "... source code of src/components/Button/examples/IconButton.js (as string)",
"renderSource": "render() {\n let foo = Icon;\n return \n {foo}\n \n ;\n}" }
]
},
{
"name": "Random Examples",
"examples": [
{
"name": "AnotherButtonExample",
"path": "path/to/.../src/components/Button/examples/AnotherButton.js",
"renderer": require("./src/components/Button/examples/AnotherButton.js"),
"requirePath": "./src/components/Button/examples/AnotherButton.js",
"description": "",
"source": "... source code of src/components/Button/examples/AnotherButton.js (as string)",
"renderSource": "render() {\n return ;\n}"
}
]
}
]
Usage
$3
> react-component-illustrator --pattern path/to/components/*/examples/.js --outputFormat commonjs --dest ./dist
#### Options
##### --pattern, -p (one or more)
Path(s) to the examples, could be either glob or absolute path
##### --verbose, -v (optional)
Also prints the result in console.
##### --dest, -d (optional)
The path to the file where output should be saved.
##### --outputFormat, -f (optional, default: 'commonjs')
The type of output, one of:
- commonjs
module.exports = [
{
name: 'MyComponent',
description: '',
props: [...],
examples: [
{
name: 'MyComponentExample',
renderer: require('path/to/MyComponentExample.js'),
...
}
]
},
...
];
- es6
export default [
{
name: 'MyComponent',
description: '',
props: [...],
examples: [
{
name: 'MyComponentExample',
renderer: require('path/to/MyComponentExample.js'),
...
}
]
},
...
];
- string
[
{
name: 'MyComponent',
description: '',
props: [...],
examples: [
{
name: 'MyComponentExample',
...
}
]
},
...
];
$3
import {illustrate} from 'react-component-illustrator';illustrate('path/to/components/*/examples/.js')
.then(function (illustrations) {
console.log(illustrations);
})
.catch(console.error.bind(console))
;
MIT