Spinne

Spins a web of component relationships for react projects

WIP: Spinne is in early development and report structure and cli options are subject to change.

Spinne is a CLI Tool, that analyzes react projects, and creates a component graph from all components that are used. This allows you to make some educated guesses about:

• component usage
• component relationships

Example

Spinne can analyze both single React projects and workspaces containing multiple projects. Here's an example output showing component relationships across multiple projects:

[
  {
    "name": "source-lib",
    "graph": {
      "components": [
        {
          "id": 11611080489164640768,
          "name": "Button",
          "path": "source-lib/src/components/Button.tsx",
          "props": {
            "label": 1,
            "onClick": 1
          }
        }
      ],
      "edges": []
    }
  },
  {
    "name": "consumer-app",
    "graph": {
      "components": [
        {
          "id": 14300231078674835378,
          "name": "App",
          "path": "consumer-app/src/App.tsx",
          "props": {}
        }
      ],
      "edges": [
        {
          "from": 14300231078674835378,
          "to": 11611080489164640768,
          "project_context": "source-lib"
        }
      ]
    }
  }
]

For the graph, we use a directed graph where relationships between components are represented by edges. Each component has a unique ID and belongs to a project (indicated by the outer name field). Edges can be within the same project or across projects, with the project_context field indicating when a component depends on a component from another project.

In this example:

• The Button component is defined in the source-lib project
• The App component in consumer-app uses the Button component
• The edge from App to Button includes project_context: "source-lib" to indicate it's a cross-project dependency
• Component props are tracked with usage counts (e.g., "label": 1 means the prop is used once)

Installation

Spinne is a command line tool written in rust, so the easiest way to install it is via cargo:

cargo install spinne

Usage

To scan for components in your current directory:

spinne

This command will output the results in a file named 'spinne-report.json' by default. If you want to output it directly to the console you can use -f console:

spinne -f console

To generate an interactive HTML visualization of the component graph:

spinne -f html

This will create 'spinne-report.html' and automatically open it in your default browser.

To analyze specific entry points for exports:

spinne --entry-points src/index.tsx,src/components/index.ts

This will analyze the specified files for exported components before performing the normal component graph analysis.

Options

Configuration File

You can also configure Spinne using a spinne.json file in your project root. This file allows you to define persistent configuration options that will be used every time you run Spinne.

Example spinne.json:

{
  "include": ["**/*.tsx", "**/*.ts"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.tsx"],
  "entry_points": ["src/index.tsx", "src/components/index.ts"]
}

Configuration Options

The configuration file options will be merged with any command line arguments you provide. For example, if you specify both exclude patterns in your spinne.json and via the --exclude flag, both sets of patterns will be used.

Workspace Support

Spinne automatically detects and analyzes all React projects within a workspace. A project is identified by the presence of both a package.json file and a .git directory. This means Spinne can:

• Handle projects in subdirectories
• Process multiple independent projects in a directory structure

When analyzing a workspace:

1. Spinne first discovers all valid React projects in the directory tree
2. Each project is analyzed independently
3. Component relationships are tracked per project
4. Results are aggregated in the final output

You can run Spinne at any level of your directory structure:

• Run it in a specific project directory to analyze just that project
• Run it in a workspace root to analyze all contained projects
• Run it in any parent directory to discover and analyze all projects beneath it

# Analyze a specific project
cd my-project && spinne

# Analyze multiple projects from a parent directory
cd dev/projects && spinne