@animaapp/vite-plugin-screen-graph NPM

@animaapp/vite-plugin-screen-graph

A Vite plugin that generates a graph of screen navigation in React applications.

Installation

npm install --save-dev @animaapp/vite-plugin-screen-graph
# or
yarn add --dev @animaapp/vite-plugin-screen-graph
# or
pnpm add -D @animaapp/vite-plugin-screen-graph

Usage

Add the plugin to your vite.config.ts file:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { screenGraphPlugin } from '@animaapp/vite-plugin-screen-graph';

export default defineConfig({
  plugins: [
    react(),
    screenGraphPlugin()
  ],
});

When you build your project, the plugin will analyze your React components and generate a .screen-graph.json file in the root of your project. This file contains a graph representation of your application's screen navigation.

How it works

The plugin analyzes your React components and identifies navigation between screens by looking for:

<Link> and <NavLink> components from React Router
<Navigate> components from React Router
<a> tags with href attributes
navigate() function calls from React Router

It then builds a graph where:

Nodes represent screens (React components associated with routes)
Edges represent navigation paths between screens

Output format

The generated .screen-graph.json file has the following structure:

{
  "nodes": [
    {
      "id": "path/to/HomeScreen.tsx",
      "label": "HomeScreen",
      "isRoot": true
    },
    {
      "id": "path/to/ProfileScreen.tsx",
      "label": "ProfileScreen"
    },
    // ...
  ],
  "edges": [
    {
      "id": "path/to/HomeScreen.tsx:42:10-to-path/to/ProfileScreen.tsx",
      "source": "path/to/HomeScreen.tsx",
      "target": "path/to/ProfileScreen.tsx",
      "data": {
        "viaRoute": "/profile",
        "trigger": {
          "element": "<Link to=\"/profile\">Go to Profile</Link>",
          "line": 42,
          "column": 10,
          "sourceFile": "path/to/HomeScreen.tsx"
        }
      }
    },
    // ...
  ]
}

Node Structure

id: The full file path to the component, ensuring uniqueness even if multiple components have the same name
label: The component name (basename of the file without extension) for display purposes
isRoot: A boolean flag (only present on the root screen) indicating if this is the root screen (path: "/")

Edge Structure

id: A unique identifier combining the source location (file, line, column) and target file
source: The source node ID (file path)
target: The target node ID (file path)
data: Additional information about the navigation
- viaRoute: The route path used for navigation
- trigger: Information about what triggered the navigation
  - element: The full element snippet that triggered the navigation (e.g., <Link to="/profile">Go to Profile</Link>)
  - line: The line number in the source file
  - column: The column number in the source file
  - sourceFile: The source file path