react-scanner statically analyzes the given code (TypeScript supported) and extracts React components and props usage.

First, it crawls the given directory and compiles a list of files to be scanned. Then, it scans every file and extracts rendered components and their props into a JSON report.

For example, let's say we have the following index.js file:

import React from "react";
import ReactDOM from "react-dom";
import {
  BasisProvider,
  defaultTheme,
  Container,
  Text,
  Link as BasisLink,
} from "basis";

function App() {
  return (
    <BasisProvider theme={defaultTheme}>
      <Container margin="4" hasBreakpointWidth>
        <Text textStyle="subtitle2">
          Want to know how your design system components are being used?
        </Text>
        <Text margin="4 0 0 0">
          Try{" "}
          <BasisLink href="https://github.com/moroshko/react-scanner" newTab>
            react-scanner
          </BasisLink>
        </Text>
      </Container>
    </BasisProvider>
  );
}

ReactDOM.render(<App />, document.getElementById("root"));

Running react-scanner on it will create the following JSON report:

{
  "BasisProvider": {
    "instances": [
      {
        "importInfo": {
          "imported": "BasisProvider",
          "local": "BasisProvider",
          "moduleName": "basis"
        },
        "props": {
          "theme": "(Identifier)"
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/index.js",
          "start": {
            "line": 13,
            "column": 5
          }
        }
      }
    ]
  },
  "Container": {
    "instances": [
      {
        "importInfo": {
          "imported": "Container",
          "local": "Container",
          "moduleName": "basis"
        },
        "props": {
          "margin": "4",
          "hasBreakpointWidth": null
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/index.js",
          "start": {
            "line": 14,
            "column": 7
          }
        }
      }
    ]
  },
  "Text": {
    "instances": [
      {
        "importInfo": {
          "imported": "Text",
          "local": "Text",
          "moduleName": "basis"
        },
        "props": {
          "textStyle": "subtitle2"
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/index.js",
          "start": {
            "line": 15,
            "column": 9
          }
        }
      },
      {
        "importInfo": {
          "imported": "Text",
          "local": "Text",
          "moduleName": "basis"
        },
        "props": {
          "margin": "4 0 0 0"
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/index.js",
          "start": {
            "line": 18,
            "column": 9
          }
        }
      }
    ]
  },
  "Link": {
    "instances": [
      {
        "importInfo": {
          "imported": "Link",
          "local": "BasisLink",
          "moduleName": "basis"
        },
        "props": {
          "href": "https://github.com/moroshko/react-scanner",
          "newTab": null
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/index.js",
          "start": {
            "line": 20,
            "column": 11
          }
        }
      }
    ]
  }
}

This raw JSON report is used then to generate something that is useful to you. For example, you might want to know:

• How often a cetrain component is used in your design system? (see count-components processor)
• How often a certain prop in a given component is used? (see count-components-and-props processor)
• Looking at some prop in a given component, what's the distribution of values used? (e.g. you might consider deprecating a certain value)

Once you have the result you are interested in, you can write it to a file or simply log it to the console.

npm install --save-dev react-scanner

npx react-scanner -c /path/to/react-scanner.config.js

Everything that react-scanner does is controlled by a config file.

The config file can be located anywhere and it must export an object like this:

module.exports = {
  crawlFrom: "./src",
  includeSubComponents: true,
  importedFrom: "basis",
};

Running react-scanner with this config would output something like this to the console:

{
  "Text": {
    "instances": 17,
    "props": {
      "margin": 6,
      "color": 4,
      "textStyle": 1
    }
  },
  "Button": {
    "instances": 10,
    "props": {
      "width": 10,
      "variant": 5,
      "type": 3
    }
  },
  "Footer": {
    "instances": 1,
    "props": {}
  }
}

It is also possible to run the scanner programmatically. In this case, the config options should be passed directly to the run function.

import scanner from "react-scanner";

const output = await scanner.run(config);

Here are all the available config options:

Scanning the files results in a JSON report. Add processors to tell react-scanner what to do with this report.

react-scanner comes with some ready to use processors.

To use a built-in processor, simply specify its name as a string, e.g.:

processors: ["count-components"]

You can also use a tuple form to pass options to a built-in processor, e.g.:

processors: [
  ["count-components", { outputTo: "/path/to/my-report.json" }]
]

All the built-in processors support the following options:

Here are the built-in processors that react-scanner comes with:

Example output:

{
  "Text": 10,
  "Button": 5,
  "Link": 3
}

Example output:

{
  "Text": {
    "instances": 17,
    "props": {
      "margin": 6,
      "color": 4,
      "textStyle": 1
    }
  },
  "Button": {
    "instances": 10,
    "props": {
      "width": 10,
      "variant": 4,
      "type": 2
    }
  },
  "Footer": {
    "instances": 1,
    "props": {}
  }
}

Example output:

{
  "Text": {
    "instances": [
      {
        "props": {
          "textStyle": "subtitle2"
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/file",
          "start": {
            "line": 9,
            "column": 9
          }
        }
      },
      {
        "props": {
          "margin": "4 0 0 0"
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/file",
          "start": {
            "line": 12,
            "column": 9
          }
        }
      }
    ]
  },
  "Link": {
    "instances": [
      {
        "props": {
          "href": "https://github.com/moroshko/react-scanner",
          "newTab": null
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/file",
          "start": {
            "line": 14,
            "column": 11
          }
        }
      }
    ]
  },
  "Container": {
    "instances": [
      {
        "props": {
          "margin": "4",
          "hasBreakpointWidth": null
        },
        "propsSpread": false,
        "location": {
          "file": "/path/to/file",
          "start": {
            "line": 8,
            "column": 7
          }
        }
      }
    ]
  }
}

We saw above that built-in processors come in the form of a string or a tuple.

Custom processors are functions, and can be asynchronous!

If the processor function returns a Promise, it will be awaited before the next processor kicks in. This way, you can use previous processors results in your processor function.

Here is an example of taking the output of the built-in count-components-and-props processor and sending it to your storage solution.

processors: [
  "count-components-and-props",
  ({ prevResult }) => {
    return axios.post("/my/storage/solution", prevResult);
  }
]

Processor functions receive an object with the following keys in it:

When a primitive (strings, numbers, booleans, etc...) is passed as a prop value into a component, the raw report will display this literal value. However, when expressions or variables are passed as a prop value into a component, the raw report will display the AST type. In some instances, we may want to see the actual expression that was passed in.

Using the getPropValue configuration parameter makes this possible.

type IGetPropValue = {
    /** The AST node */
    node: Node,
    componentName: string,
    propName: string,
    /** Pass the node back into this method for default handling of the prop value */
    defaultGetPropValue: (node: Node) => string
}
getPropValue({ node, componentName, propName, defaultGetPropValue }: IGetPropValue): string

If we were building out a design system, and wanted to see all the variations of a style prop that we passed into an Input component, we could do something like this:

const escodegen = require("escodegen-wallaby");

getPropValue: ({ node, propName, componentName, defaultGetPropValue }) => {
  if (componentName === "Input" && propName === "style") {
    if (node.type === "JSXExpressionContainer") {
      return escodegen.generate(node.expression);
    } else {
      return escodegen.generate(node);
    }
  } else {
    return defaultGetPropValue(node);
  }
};

MIT