Package Brain — Visualiza y monitorea tus design system packages.

StackBrain is a local tool (CLI + webapp) that lets you visualize and monitor your design system packages. It parses your source code, extracts components, tokens, and health metrics, and presents everything in a clean dashboard.

npx stackbrain

One command. Opens a local webapp at localhost:3777 with 4 views: Components, Tokens, Packages, and Health.

# Run directly (no install needed)
npx stackbrain

# Or install globally
npm install -g stackbrain
stackbrain

On first run, register your package:

npx stackbrain add-package

Catalogs every component exported from your package. Parses barrel exports, detects categories, props, variants, and external dependencies — all via regex (no TypeScript compiler needed).

• Category filters (flat, compound, motion, SEO, etc.)
• Line count, test status, external deps per component
• Co-exports detection (sub-components)

Extracts and displays your design tokens:

• Color scales (primary, brand colors)
• Spring presets (gentle, smooth, snappy, bounce)
• Shadow levels
• CSS variables
• Keyframes and utilities

Tracks registered packages and their consumers:

• Version matrix across projects
• Entry points (components, hooks, theme, motion, etc.)
• Outdated version detection

Aggregated health dashboard:

• Test results (passed/failed/skipped)
• Bundle sizes per entry point
• Changelog (recent versions)
• Consumer version matrix

npx stackbrain              # Open webapp at localhost:3777
npx stackbrain scan         # Print package summary in terminal
npx stackbrain add-package  # Register a package interactively
npx stackbrain doctor       # Verify paths, versions, and config

CLI (Commander) -> Hono Server -> Vite SPA (React 19)
                       |
                Services layer
                       |
                Filesystem (package source + ~/.stackbrain/registry.json)

1. Registry at ~/.stackbrain/registry.json stores your packages and consumers
2. ComponentService parses your barrel export (index.ts) to detect all components
3. TokenService reads theme files, CSS variables, and motion presets
4. PackageService reads package.json from your package and consumers to build version matrix
5. HealthService aggregates test results, bundle sizes, and changelogs

No database. No cloud. Everything runs locally on your filesystem.

All data is served via REST endpoints:

GET /api/components              # List all components
GET /api/components/categories   # Grouped by category
GET /api/components/:slug        # Component detail (props, variants)

GET /api/tokens                  # All design tokens
GET /api/tokens/colors           # Color scales only
GET /api/tokens/motion           # Springs and motion variants

GET /api/packages                # Registered packages
GET /api/packages/:name          # Package detail with entry points
GET /api/packages/:name/consumers # Version matrix

GET /api/health                  # Aggregated health dashboard
GET /api/health/:slug            # Health for a specific package

git clone https://github.com/curetcore/stackbrain
cd stackbrain
npm install
npm run dev     # Watch mode (CLI + webapp)
npm run test    # Run tests
npm run build   # Production build

MIT - Ronaldo Paulino