Stop Vibe Coding debt. Audit your codebase, replace reinvented wheels with
unicorn-grade libraries, and ship a migration plan + "delete-code" checklist.
English | 简体中文
Quick Start • Features • How It Works • Comparison • API • Examples • Contributing
--- ## Why Next-Unicorn? Every codebase accumulates hand-rolled implementations that should be mature libraries. Custom date formatters, DIY loggers, bespoke state machines, ad-hoc i18n — **Vibe Coding debt**. Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't find code you wrote that *should become* a dependency — or capabilities your project is *missing entirely*. **Next-Unicorn does all three** — replacement, gap analysis, and dependency management — verified against real documentation via [Context7 MCP](https://context7.com). ## Quick Start ### From Smithery (recommended) Browse and install directly from the Smithery skill registry: > **[Next-Unicorn on Smithery](https://smithery.ai/skills/nebutra/next-unicorn-skill)** ### From npmjs.org ```bash npm install @nebutra/next-unicorn-skill # or pnpm add @nebutra/next-unicorn-skill ``` ### From GitHub Packages Configure your `.npmrc` first: ```shell echo "@nebutra:registry=https://npm.pkg.github.com" >> .npmrc ``` Then install: ```bash npm install @nebutra/next-unicorn-skill ``` ```typescript import { analyze, scanCodebase } from '@nebutra/next-unicorn-skill'; import type { Recommender, GapRecommendation } from '@nebutra/next-unicorn-skill'; // The recommender: AI agent decides which library fits each detection const recommender: Recommender = (detection) => ({ library: '@lingui/core', version: '^4.0.0', license: 'MIT', rationale: 'Compile-time i18n with near-zero runtime overhead', ecosystem: [ { library: '@lingui/macro', version: '^4.0.0', role: 'Tagged templates' }, { library: '@lingui/cli', version: '^4.0.0', role: 'CI message extraction' }, ], antiPatterns: ['Avoid i18next if bundle size matters — Lingui compiles away'], alternatives: [ { library: 'next-intl', when: 'Next.js App Router with server components' }, ], }); // Gap analysis: capabilities the project should have but doesn't const gaps: GapRecommendation[] = [ { domain: 'observability', description: 'No structured logging detected', recommendedLibrary: { name: 'pino', version: '^9.0.0', license: 'MIT', rationale: 'Fastest Node.js JSON logger with redaction and child loggers', }, priority: 'critical', }, ]; const result = await analyze({ input: { projectMetadata: { repoPath: './my-project', languages: ['typescript'], packageManagers: ['pnpm'], currentLibraries: { react: '18.2.0', next: '14.1.0' }, }, optimizationGoals: ['reduce custom code', 'improve maintainability'], constraints: { licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'] }, priorityFocusAreas: ['i18n', 'observability', 'auth-security'], }, context7Client: myContext7Client, recommender, gaps, }); if (result.success) { console.log(result.prettyJson); // result.scanResult — raw detections + structural findings for AI analysis // result.output.gapAnalysis — Context7-verified gap recommendations } ``` Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent (Claude Code, Kiro, Cursor, etc.). ## Features ### Core Analysis | Feature | Description | |---------|-------------| | **Pattern-based scanning** | Detects hand-rolled code across 31 domains with 52 regex patterns (design-system, auth, state-management, code-organization, etc.) | | **Structural analysis** | Detects monorepo architecture gaps: missing token layers, dependency flow violations, hardcoded config values | | **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't | | **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives | | **Context7 verification** | Every recommendation (replacements AND gaps) verified with exponential backoff retry | | **7-dimension impact scoring** | Scalability, performance, security, maintainability, feature richness, UX, UI aesthetics | | **Phased migration plans** | Low / medium / high risk phases with adapter strategies | | **Deletion checklists** | Every file and line range to remove, with estimated lines saved | | **UX completeness audit** | A11y, error/empty/loading states, form validation, design system alignment | | **Design system support** | Two paths: scaffold from reference repos (Primer, Polaris, Supabase, Dub) or extract from existing code | | **Code organization analysis** | Detects god directories, mixed naming conventions, deep nesting, barrel bloat, catch-all directories, and circular dependencies via import graph traversal | | **Human-in-the-loop gates** | 4 structured decision gates at irreversible/preference-driven points — triage, preferences (SWOT), accept/reject, execution confirmation | | **Monorepo support** | Detects npm, pip, cargo, go workspaces independently | ### Dependency Management | Feature | Description | |---------|-------------| | **Vulnerability scanning** | Scans current AND recommended deps via OSV — prevents "upgrade into a vuln" | | **Auto-update deps** | Impact-scored version upgrades with Context7-powered breaking change detection | | **PR auto-creation** | GitHub/GitLab PRs with conventional commit titles, impact tables, reviewer checklists | | **Migration PRs** | PRs with adapter code scaffolding for hand-rolled code replacement | ## How It Works ### Architecture Diagram ```mermaid flowchart TB subgraph input [Input] I[InputSchema JSON] end subgraph deterministic [Deterministic Layer — TypeScript] V[Zod Validator] S[Scanner — 52 regex patterns across 31 domains] SA[Structure Analyzer — monorepo architecture, dependency flow, token layers] C7[Context7 Verifier — exponential backoff, query ranking] VS[Vuln Scanner — OSV database] PC[Peer Checker — semver range validation] PR[PR Strategy + Executor] end subgraph agent [AI Agent Layer — Claude generalization] GA[Gap Analysis — single library / ecosystem / architecture gaps] REC[Recommender — ecosystem-level solutions with rationale] UX[UX Audit — 8 categories] DS{Design System?} DSE[Extract from existing code] DSS[Scaffold from reference repos] end subgraph output [Output] O[OutputSchema JSON] end I --> V --> S S --> SA S --> REC SA --> GA GA --> DS DS -->|Existing frontend| DSE DS -->|No frontend| DSS GA --> O REC --> C7 --> O S --> PC --> O S --> VS --> O UX --> O O --> PR ``` ### Design Principles | Principle | Implementation | |-----------|---------------| | **Occam's Razor** | Only 17 TS modules remain — each does something Claude cannot (regex, semver, file I/O, API calls, import graph traversal). Scoring, planning, UX audit, PR descriptions are AI-agent-driven. | | **No hardcoded recommendations** | Pattern catalog contains zero library names. The `Recommender` callback and `GapRecommendation` are filled by the AI agent at runtime. | | **Context7 best practices** | Exponential backoff (3 retries), query parameter for ranking, per-library isolation. Both replacements and gaps are verified. | | **Progressive disclosure** | SKILL.md is 111 lines. `references/` files load only when design system gaps are detected. | | **Two analysis modes** | **Replacement**: scanner finds hand-rolled code → agent recommends library. **Gap**: agent identifies missing capabilities → verified via Context7. | | **Design system support** | Structure analyzer detects missing layers. Two paths: scaffold from 25+ reference repos, or extract spec from existing code (6 principles, 5 phases). | Each stage is a pure function with structured I/O. All external dependencies (Context7, OSV, npm registry, GitHub API) are **injected via interfaces** for testability. ### Before / After| Before (hand-rolled) | After (recommended) |
|---|---|
| ```tsx // Custom i18n across 47 files const translations = { en: { greeting: 'Hello' }, es: { greeting: 'Hola' }, }; function t(key, locale) { return translations[locale]?.[key] ?? key; } // No plurals, no interpolation, no RTL ``` |
```tsx
// @lingui/core — Context7 verified, MIT
// Ecosystem: @lingui/macro + @lingui/cli
// Impact: 9.2/10 | Risk: low | Effort: 8h
import { useLingui } from '@lingui/react';
export default function Page() {
const { t } = useLingui();
return {t`greeting`}; } ``` |
| ```typescript // Custom logger with console.log function logRequest(req) { console.log(JSON.stringify({ time: new Date().toISOString(), method: req.method, url: req.url, })); } // No levels, no redaction, no rotation ``` | ```typescript // pino — Context7 verified, MIT // Gap analysis: "No structured logging detected" // Priority: critical import pino from 'pino'; const logger = pino({ level: 'info', redact: ['req.headers.authorization'], }); ``` |