A CLI and library to extract information from React component files for documentation generation purposes.
MIT License
Bot releases are visible (Hide)
@caabernathy added new information to method parameters ( #83 ). If the parameter has a flow type, the name of the type is no also included. I.e. if the type definition is:
export type StatusBarStyle = $Enum<{
...
}
the docs for a parameter of that type will include alias: "StatusBarStyle"
.
In addition the docs now include an optional
field indicating whether the parameter is optional or nor.
This version adds a great new feature: Support for Flow type definitions. Thanks a lot to @danez for implementing this feature ( #48 ).
react-docgen is now able to extract type definitions as in this example:
import React, { Component } from 'react';
type Props = {
/** Description of prop "foo". */
primitive: number,
/** Description of prop "bar". */
literalsAndUnion: 'string' | 'otherstring' | number,
arr: Array<any>,
func?: (value: string) => void,
obj?: { subvalue: ?boolean },
};
/**
* General component description.
*/
export default class MyComponent extends Component<void, Props, void> {
props: Props;
render(): ?ReactElement {
// ...
}
}
In the JSON output, every prop will have a new field named flowType
. If you use both, flow (for static type checks) and React propTypes (for dynamic type checks) you can do so without any collisions. The JSON blob now simply contains more information and you can decide which one to use for your documentation.
Have a look at the more extensive description in the README to learn how flow types are represented.
--resolver
CLI optionThe --resolver
lets you specify from the CLI which resolver* to use. It can either be the name of a built-in resolver or a path to a JavaScript module that exports a resolver function:
react-docgen --resolver findExportedComponentDefinition ./path/to/component.js
# same as
react-docgen ./path/to/component.js
react-docgen --resolver findAllComponentDefinitions ./path/to/component.js
react-docgen --resolver ./path/to/custom/resolver.js ./path/to/component.js
* Resolvers contain the logic to find React component definitions in the JavaScript files.
Variables used for propTypes
and defaultProps
, e.g.
MyClass.defaultProps = defaultProps;
are now properly resolved for class
and stateless components. Thanks to @oliviertassinari for reporting this issue! ( #45, #46 )
Since React v0.14, components can be defined as simple functions:
function SimpleComponent(props) {
return <div>{this.props.soSimple}</div>
}
Thanks to @iamdustan, react-docgen
is now able to detect these components as well. The findExportedComponentDefinition
and findAllComponentDefinitions
have been updated accordingly.
A function is considered to be a stateless React component if we can determine that it returns a JSX element or the result of a React.createElement
call. As always, there are limits to what can be achieved with static analysis, so it might not detect every possible case (but maybe your component is too complex then anways? ;) ).
The propTypeCompositionHandler
was not part of the default handlers and therefore the generated documentation didn't contain information about composition.
(I wasn't sure whether this should be considered to be a bug fix or new feature, but I went with new feature instead)
Consider docblock above decorator annotations (#18). In the following example the docblock is now used for the component description:
/**
* This is the description
*/
@SomeDecorator
export default class extends React.Component {
};
Detect isRequired
in shape annotations (second part of #21)
"Short" docblocks are now recognized (#20, d3a3f3f64d3642659c224d8fbc31fe53e8d855a9):
/** Short docblock */
Docblocks on shape fields are now added to the output (#21, f5415ced5c4b6eb604b4c39093b8875d29a12239):
React.PropTypes.shape({
/**
* Field description
*/
field: React.PropTypes.string
});
produces
{
name: 'shape',
value: {
field: {
name: 'string',
description: 'Field description',
}
}
react-docgen is now able to find components defined as ES2015 classes. A class either has to extend React.Component
or has to define a render()
method in order to be recognized as React component.
Examples:
class Component extends React.Component {
// ...
}
class Component {
render() {
// ...
}
}
are both considered React components. The default resolvers have been updated and renamed accordingly.
For propTypes
, defaultProps
and other properties, react-docgen supports class properties (ES7 stage 0 proposal at the moment of this release) and assignments to the constructor function. Example:
class Component extends React.Component {
static propTypes = { ... };
}
// or
class Component extends React.Component {
// ...
}
Component.propTypes = { ... };
displayNameHandler
This new default handler adds the displayName
of a component to the documentation. Example:
var Component = React.createClass({
displayName: 'Foo',
});
class Component extends React.Component {
// ...
}
Component.displayName = 'Foo';
will result in the documentation object {displayName: 'Foo'}
.
The props
and description
properties are now not present anymore if no props or description could be extracted from the definition. I.e. instead of getting :
{
"description": "",
"props": {}
}
(like it is now), you would get
{}
This makes it easier to test for the existence of props in the first place:
if (doc.props) {
// component has props, render them
}
Documentation
classThe setDescription
and getDescription
methods are gone. Instead we added the generic set(key, value)
and get(key)
method. This allows custom handlers to add arbitrary data to the documentation. Data set this way will be added as properties to the result documentation object.
E.g. if a handler calls documentation.set('foobar', 42)
, the output will be
{
"foobar": 42
}
getMemberPathValue
is a new function which helps handlers to process component definitions, irrespectively if the definition is a React.createClass({})
call or a class Component {}
declaration.
Because react-docgen uses Babylon (Babel's parser) instead of esprima-fb now, custom handlers/resolvers might have to be updated because of slight AST representation differences.
react-docgen now understands the following constructs:
import foo from 'Foo';
import {foo} from 'Foo';
import {foo as bar} from 'Foo';
export var Component = React.createClass({});
var Component = React.createClass({});
export {Component};
export {Component as Foo};
export default Component;
export default React.createClass({});
You will now be able to use ES6 import
and export
declarations with your react components. However, to "detect" a React component, React.createClass(...)
must still be present in the source.