React Component & Prop Usage Scanner

Common errors

• TypeError: Cannot read properties of undefined (reading 'type')

  cause This error often occurs in custom `getPropValue` or `getComponentName` functions when attempting to access properties of a `value` or `local` object that might be `null` or `undefined` for certain AST nodes.
  fix Add nullish coalescing or optional chaining (`?.`) when accessing properties within your custom configuration functions, e.g., `value && value.type` or `value?.type`.

• Error: Configuration is not valid. 'rootDir' is required.

  cause The `rootDir` property is missing or empty in the `react-scanner` configuration object. Since version 0.3.0, configurations are strictly validated.
  fix Ensure your configuration object explicitly includes a `rootDir` property pointing to the base directory for scanning, e.g., `{ rootDir: './src' }`.

Warnings

• breaking The `getComponentName` configuration option was introduced in version 0.5.0. If you were relying on previous implicit component name extraction, you must explicitly configure `getComponentName: ({ local }) => local` to maintain the old behavior.
  Fix: Update your `react-scanner` configuration to include `getComponentName: ({ local }) => local` if you need to replicate the component name extraction logic from versions prior to 0.5.0.
• gotcha When no files are found to scan based on the provided configuration, `react-scanner` will now exit with an exit code of 1. This change, introduced in version 0.6.0, can cause CI/CD pipelines to fail if they expect a 0 exit code even for empty scan results.
  Fix: Ensure your scanning process handles a non-zero exit code if it's acceptable for no files to be found. Adjust CI/CD scripts to either validate file existence before running the scanner or to explicitly allow a non-zero exit code in this scenario.

Install

• npm install react-scanner npm
• yarn add react-scanner yarn
• pnpm add react-scanner pnpm

Imports

• scan
  wrong:

  import { scan } from 'react-scanner';

  correct:

  import scan from 'react-scanner';

  The primary `scan` function is exported as a default export from the main package entry point.
• countComponents
  wrong:

  import { countComponents } from 'react-scanner';

  correct:

  import { countComponents } from 'react-scanner/processors';

  Built-in processors like `countComponents` are located in the `react-scanner/processors` submodule.
• Config
  wrong:

  import { Config } from 'react-scanner';

  correct:

  import type { Config } from 'react-scanner';

  When using TypeScript, `Config` should be imported as a type for defining the scanner's configuration object.

Quickstart

Demonstrates programmatic use of `react-scanner` to scan a temporary React project and print the raw JSON report. It shows how to configure the scanner with basic options like `rootDir`, `getComponentName`, and `getPropValue` to analyze component and prop usage.

import { mkdir, writeFile, rm } from 'node:fs/promises';
import { join } from 'node:path';
import scan from 'react-scanner';

async function runScanner() {
  const tmpDir = join(process.cwd(), 'tmp-scanner-test');
  await mkdir(tmpDir, { recursive: true });

  const jsxContent = `
    import React from 'react';
    import { Button, Card } from './components';

    function App() {
      return (
        <div>
          <Button label="Click Me" onClick={() => console.log('clicked')} />
          <Card title="Hello" description="This is a test card" />
          <Button label="Submit" variant="primary" />
        </div>
      );
    }
    export default App;
  `;
  await writeFile(join(tmpDir, 'App.jsx'), jsxContent);

  const componentsContent = `
    import React from 'react';
    export const Button = ({ label, onClick, variant }) => <button>{label}</button>;
    export const Card = ({ title, description }) => <div><h3>{title}</h3><p>{description}</p></div>;
  `;
  await writeFile(join(tmpDir, 'components.js'), componentsContent);

  const config = {
    rootDir: tmpDir,
    excludedPaths: [],
    processors: [],
    getComponentName: ({ local }) => local,
    getPropValue: ({ value }) => value && value.type === 'JSXExpressionContainer' ? '(Identifier)' : value
  };

  try {
    console.log('Scanning React components...');
    const report = await scan(config);
    console.log('Generated Report:\n', JSON.stringify(report, null, 2));
  } catch (error) {
    console.error('Error during scanning:', error);
  } finally {
    await rm(tmpDir, { recursive: true, force: true });
    console.log(`Cleaned up temporary directory: ${tmpDir}`);
  }
}

runScanner();