babel-plugin-react-docgen - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0

CHANGELOG.md

 # ChangeLog
 
+### v1.3.0
+20-October-2016
+
+* Use docgen version 2.11.0. [PR11](https://github.com/kadirahq/babel-plugin-react-docgen/pull/11)
+* Rename DOC_GEN_GLOBAL to DOC_GEN_COLLECTION_NAME. [PR12](https://github.com/kadirahq/babel-plugin-react-docgen/pull/12)
+* Update the README. [PR13](https://github.com/kadirahq/babel-plugin-react-docgen/pull/13)
+
 ### v1.1.0
@@ -4,0 +11,0 @@ 20-October-2016

lib/index.js

@@ -98,7 +98,7 @@ 'use strict';
 
-  if (!state.opts.DOC_GEN_GLOBAL) {
+  if (!state.opts.DOC_GEN_COLLECTION_NAME) {
     return;
   }
 
-  var globalName = state.opts.DOC_GEN_GLOBAL;
+  var globalName = state.opts.DOC_GEN_COLLECTION_NAME;
   var filePath = p.relative('./', p.resolve('./', path.hub.file.opts.filename));
@@ -105,0 +105,0 @@ var globalNode = t.ifStatement(t.binaryExpression('!==', t.unaryExpression('typeof', t.identifier(globalName)), t.stringLiteral('undefined')), t.blockStatement([t.expressionStatement(t.assignmentExpression('=', t.memberExpression(t.identifier(globalName), t.stringLiteral(filePath), true), t.objectExpression([t.objectProperty(t.identifier('name'), t.stringLiteral(className)), t.objectProperty(t.identifier('docgenInfo'), t.memberExpression(t.identifier(className), t.identifier('__docgenInfo'))), t.objectProperty(t.identifier('path'), t.stringLiteral(filePath))])))]));

package.json

 {
-  "version": "1.2.0",
+  "version": "1.3.0",
   "name": "babel-plugin-react-docgen",
@@ -31,5 +31,5 @@ "description": "Add propType doc to react classes",
     "lodash": "4.x.x",
-    "react-docgen": "2.x.x"
+    "react-docgen": "2.11.0"
   },
   "license": "MIT"
 }

README.md

 # babel-plugin-react-docgen
 
-Add propType doc to react classes
+[react-docgen](https://github.com/reactjs/react-docgen) allows you to write propType descriptions, class descriptions and access propType metadata programatically.
 
-## Installation
+This babel plugin allow you to access those information right inside your React class.
 
-```sh
-$ npm install babel-plugin-react-docgen
+For an example, let's say you've a React class like this:
+
+```js
+/**
+  This is an awesome looking button for React.
+*/
+import React from 'react';
+
+export default class Button extends React.Component {
+  render() {
+    const { label, onClick } = this.props;
+    return (
+      <button onClick={onClick}>{ label }</button>
+    );
+  }
+}
+
+Button.propTypes = {
+  /**
+    Label for the button.
+  */
+  label: React.PropTypes.string,
+
+  /**
+    Triggered when clicked on the button.
+  */
+  onClick: React.PropTypes.func,
+};
 ```
 
+With this babel plugin, you can access all these information right inside your app with:
+
+```js
+console.log(Button.__docgenInfo);
+```
+<details>
+  <summary>Click to see the output</summary>
+
+  ```js
+  {
+    description: 'This is an awesome looking button for React.',
+    props: {
+      label: {
+        type: {
+          name: 'string'
+        },
+        required: false,
+        description: 'Label for the button.'
+      },
+      onClick: {
+        type: {
+          name: 'func'
+        },
+        required: false,
+        description: 'Triggered when clicked on the button.'
+      }
+    }
+  }
+  ```
+</details>
+
+This will be pretty useful for documentations and some other React devtools like [Storybook](https://github.com/kadirahq/react-storybook).
+
 ## Usage
 
-### Via `.babelrc` (Recommended)
+Install the plugin:
 
-**.babelrc**
+```sh
+npm install -D babel-plugin-react-docgen
+```
 
+Use it inside your `.babelrc`
+
 ```json
 {
-  "plugins": ["babel-plugin-react-docgen"]
+  "plugins": ["react-docgen"]
 }
 ```
 
-### Via CLI
+## Collect All Docgen Info
 
-```sh
-$ babel --plugins babel-plugin-react-docgen script.js
+Sometimes, it's a pretty good idea to collect all of the docgen info into a collection. Then you could use that to render style guide or similar.
+
+So, we allow you to collect all the docgen info into a global collection. To do that, add following config to when loading this babel plugin:
+
+```json
+{
+  "plugins":[
+    ["babel-plugin-react-docgen", { "DOC_GEN_COLLECTION_NAME": "MY_REACT_DOCS"}]
+  ]
+}
 ```
 
-### Via Node API
+Then you need to create a global variable(an object) in your app called `MY_REACT_DOCS` before any code get's executed.
+Then we'll save them into that object. We do it by adding a code block like this to the transpiled file:
 
-```javascript
-require("babel-core").transform("code", {
-  plugins: ["babel-plugin-react-docgen"]
-});
+```js
+if (typeof MY_REACT_DOCS !== 'undefined') {
+  MY_REACT_DOCS['test/fixtures/case4/actual.js'] = {
+    name: 'Button',
+    docgenInfo: Button.__docgenInfo,
+    path: 'path/to/my/button.js'
+  };
+}
 ```
 
-## Guide
+## Compile Performance
 
-* React class information is avalable via `<ClassName>.__docgenInfo` as a JSON parsabel string.
-* This plugin uses `react-docgen` under the hood, so every [limitation](https://github.com/reactjs/react-docgen#guidelines-for-default-resolvers-and-handlers) it has, applies.
-* If you need a global object with all the react component docs, set plugin options like this in `.babelrc` (replace <your global name> with variable name you want)
-```
-"plugins":[["babel-plugin-react-docgen", {"DOC_GEN_GLOBAL": "<your global name>"}]]
-```
+Now, we parse your code with `react-docgen` to get these info.
+But we only do it for files which has a React component.
+
+Yes, this will add some overhead to your project. But once you turned on [babel cache directory](http://stackoverflow.com/a/30384710) this won't be a big issue.
+
+## Output Size
+
+Yes this increase the output size of your transpiled files. The size increase varies depending on various factors like:
+
+* How many react classes you've
+* Amount of docs you've written
+* Amount of propTypes you've
+
+Most of the time, you need this plugin when you are developing your app or with another tool like [Storybook](https://github.com/kadirahq/react-storybook). So, you may not need to use this on the production version of your app.

test/index.js

@@ -24,3 +24,3 @@ import path from 'path';
           [plugin, {
-            "DOC_GEN_GLOBAL": "STORYBOOK_REACT_CLASSES"
+            "DOC_GEN_COLLECTION_NAME": "STORYBOOK_REACT_CLASSES"
           }]
@@ -27,0 +27,0 @@ ],

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

121189

increased by3.26%

Number of package files

22

increased by4.76%

Number of lines in readme file

129

increased by186.67%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedansi-styles@1.0.0(transitive)

• + Addedast-types@0.9.6(transitive)

• + Addedasync@1.5.2(transitive)

• + Addedchalk@0.4.0(transitive)

• + Addeddoctrine@1.5.0(transitive)

• + Addedesprima@3.1.3(transitive)

• + Addedhas-color@0.1.7(transitive)

• + Addedisarray@1.0.0(transitive)

• + Addednomnom@1.8.1(transitive)

• + Addedreact-docgen@2.11.0(transitive)

• + Addedrecast@0.11.23(transitive)

• + Addedsource-map@0.5.7(transitive)

• + Addedstrip-ansi@0.1.1(transitive)

• + Addedunderscore@1.6.0(transitive)

• - Removedast-types@0.10.1(transitive)

• - Removedasync@2.6.4(transitive)

• - Removedcommander@2.20.3(transitive)

• - Removeddoctrine@2.1.0(transitive)

• - Removedesprima@4.0.1(transitive)

• - Removedreact-docgen@2.21.0(transitive)

• - Removedrecast@0.12.9(transitive)

• - Removedsource-map@0.6.1(transitive)

• Updatedreact-docgen@2.11.0