libRARian 📚

Component Librarian for React/Next.js codebases — scan, catalog, and deduplicate UI components.

libRARian scans your codebase, finds every component, counts how many times each is used, and generates a catalog with extraction candidates — components that share patterns and should be unified into shared primitives.

Install

npm install -g librarian
# or run directly:
npx librarian

Quick Start

# Scan default directories (src/components/ui, src/components/crm, src/components/control)
librarian

# Scan a specific directory
librarian src/components

# Scan specific subdirectories
librarian src/components --dirs ui cards modals

# Output as JSON
librarian --format json

# Output both Markdown + JSON
librarian --format both

# Skip usage counting (faster, just find components)
librarian --no-usage

# Custom output path
librarian -o docs/component-catalog.md

# Custom extraction threshold (default: 3)
librarian -t 5

What It Does

Phase 1: Scan 🔍

Finds all .tsx and .jsx component files in the target directories. Extracts component names, props interfaces, and file paths.

Phase 2: Count 📊

Greps the entire codebase for import statements referencing each component. Shows you which components are heavily used and which are dead code.

Phase 3: Catalog 📝

Generates a COMPONENT-CATALOG.md with:

• Components grouped by category
• Usage counts
• Status indicators (stable / needs-review / deprecated)

Phase 4: Candidates 🔗

Identifies extraction candidates — patterns that appear 3+ times and should be unified:

• Components with the same suffix (StatusBadge, StageBadge, CountBadge → all Badges)
• Duplicate component names in different directories
• Components with similar prop interfaces

Output Example

# Component Catalog — Auto-generated by libRARian

> **Components:** 99 | **Categories:** 7

## Buttons & Actions
- **Button** — `src/components/ui/button.tsx` | Uses: **110** | ✅ stable
- **ConfirmDialog** — `src/components/ui/confirm-dialog.tsx` | Uses: **35** | ✅ stable

## 🔥 Extraction Candidates
1. **4 Badge variants** — StatusBadge, StageBadge, CountBadge, RatingStars
   All map values to colors — extract a shared StatusIndicator component.

Programmatic API

import { scanComponents, countUsages, generateCatalog, findCandidates } from 'librarian';

const components = scanComponents('src/components', ['ui', 'crm']);
const withUsages = countUsages(components, process.cwd());
const catalog = generateCatalog(withUsages);
const candidates = findCandidates(withUsages, 3);

Why "libRARian"?

The capitalized RAR in the middle is a nod to:

• React Analytics & Reporting
• RAR compression — we're compressing your component sprawl into reusable primitives
• The librarian who keeps the library organized 📚

License

MIT — Built by Boottify