WebStorm Plugin for React UI-kit Contracts

React Component Contract Guard: WebStorm Plugin to Prevent UI Kit Drift

In large frontend projects, the UI kit starts drifting between TypeScript types, actual JSX usage, and Storybook stories. Components with dozens of uses accumulate undocumented props, outdated stories, and hidden dependencies. Standard TypeScript catches syntax errors but misses the big questions: Is the mismatch isolated or systemic? How many places will a prop change affect? Does Storybook reflect the current API?

Component Contract Guard tackles this with a contract analyzer and WebStorm plugin. The tool builds a component model from three sources: TypeScript contracts, JSX usages, and Storybook args, highlighting discrepancies right in the editor.

Here's a typical component example:

type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary";
  icon?: React.ReactNode;
};

export function Button({ label, variant = "primary", icon }: ButtonProps) {
  return (
    <button data-variant={variant}>
      {icon}
      {label}
    </button>
  );
}

But in the project, you see:

<Button variant="primary" tone="loud" />
<Card title="Health" variant="ghost" />

Storybook might reference nonexistent mystery: true.

Architecture: CLI Analyzer + IDE Plugin

The project splits into two layers for independence and reusability:

• CLI Analyzer (TypeScript): Loads tsconfig.json, creates a TypeScript Program, extracts prop contracts from TSX component exports, gathers JSX usages, parses CSF Storybook.

• WebStorm Plugin (Kotlin): Runs the CLI, parses JSON results, displays inline hints, underlines, tooltips, file summaries, and impact reports.

This separation enables CLI use in CI, avoids logic duplication, and eases porting to other IDEs.

Analysis runs in three stages:

• Contract Collection: Extracts prop names, types, required status, defaults, JSDoc. Handles destructuring with defaults.

• Usage Collection: JSX positions, passed props, spread expressions (with cautious warnings).

• Storybook Parsing: meta.args, argTypes, story objects.

Analyzer Signals and Warnings

The plugin generates precise warnings:

• Unknown prop passed (e.g., tone on Button).
• Missing required prop (e.g., label).
• Storybook references unknown prop (mystery).
• Contract prop not reflected in Storybook.
• Unused prop in neither code nor stories.

For each prop, it calculates impact:

• Number of code usages.
• Number of story usages.
• Change risk (scored by frequency).

This distinguishes local tweaks from public API migrations.

Warning examples:

• Unknown prop "tone" is passed to Button
• Button is missing required props: label
• Story BrokenStory references unknown prop "mystery" for Button
• Button.icon is not documented in Storybook args/argTypes

WebStorm Integration: Inline Signals

The plugin triggers on file open/save: CLI scan → JSON → UI elements.

Display channels:

• Inline badges over problematic lines.
• Wave underlines for JSX sections.
• Hover tooltips with details and fixes.
• File-level summary at the top.
• Tool window for project overview and prop impact.

The flow seamlessly integrates into the editor without conflicts.

Target Use Cases

The tool shines for:

• UI kits and design systems.
• Internal component libraries.
• Large monorepos with 50+ components.
• Projects where Storybook serves as the documentation contract.

In small projects (3–5 components), manual review suffices; drift emerges at scale.

Key Highlights

• Control Object: Not AST or files, but contracts as links between types/usages/docs/impact.
• TypeScript Compiler API: Precise prop parsing without shortcuts.
• Spread Handling: Cautious warnings for dynamic props.
• Impact Scoring: Quantitative migration risk assessment.
• IDE Integration: Inline signals as workflow natives, not external CLI.

Future Development

The MVP focuses on core analysis. Roadmap:

• Breaking change detection across versions.
• Auto-migration prop suggestions.
• CI/PR integration.
• Wrapper component support.
• Deeper Storybook analysis.
• Impact grouping by project layers.

— Editorial Team