Skip to content

Latest commit

 

History

History
512 lines (403 loc) · 13.6 KB

IMPLEMENTATION.md

File metadata and controls

512 lines (403 loc) · 13.6 KB

Codebase Implementation - Complete Tech Paradigm

Overview

This document describes the complete implementation of the "codebase" project - a code library inspired by shadcn/ui that organizes the shadcn/ui ecosystem with a clear architectural separation between UI components, Atoms, and Templates.

Architecture

Three-Layer System

┌──────────────────────────────────────┐
│          Templates                   │ ← Page sections (shadcn blocks)
├──────────────────────────────────────┤
│             Atoms                    │ ← Composed components
├──────────────────────────────────────┤
│         UI Components                │ ← shadcn/ui primitives
├──────────────────────────────────────┤
│        Radix UI Primitives          │ ← Base layer
└──────────────────────────────────────┘

Layer 1: UI Components (src/components/ui/)

  • Direct shadcn/ui primitives (Button, Card, Dialog, etc.)
  • 50+ components
  • Installed via shadcn CLI

Layer 2: Atoms (src/components/atom/)

  • 31 enhanced, composed components
  • Organized by category: ai/, form/, display/, navigation/, feedback/
  • Examples: ai-prompt-input, infinite-slider, modal system

Layer 3: Templates (src/components/template/)

  • 8 complete page sections
  • Versioned naming (header-01, header-02, sidebar-01, etc.)
  • Production-ready layouts

File Structure

codebase-underway/
├── src/
│   ├── components/
│   │   ├── ui/                          # 50 shadcn/ui components
│   │   ├── atom/                        # 31 atoms (organized by category)
│   │   │   ├── ai/                      # AI components
│   │   │   └── modal/                   # Modal system
│   │   └── template/                    # 8 templates (versioned)
│   │
│   ├── registry/
│   │   ├── default/
│   │   │   ├── atoms/
│   │   │   │   └── _registry.ts         # Atoms registry
│   │   │   ├── templates/               # Template components
│   │   │   └── ui/                      # UI components
│   │   ├── registry-templates.ts        # Template definitions
│   │   ├── registry-categories.ts       # Category mappings
│   │   └── schema.ts                    # TypeScript interfaces
│   │
│   ├── app/[lang]/(root)/atoms/        # Atoms documentation routes
│   │   ├── [[...slug]]/page.tsx        # Dynamic atom pages
│   │   └── layout.tsx                   # Atoms layout
│   │
│   └── components/root/template/
│       └── registry.ts                  # Zod validation schemas
│
├── content/atoms/(root)/               # 32 MDX documentation files
│   ├── index.mdx                       # Introduction
│   ├── accordion.mdx                   # Example
│   └── [31 other atoms].mdx           # Generated docs
│
├── scripts/
│   ├── build-registry.mts             # Registry build system
│   ├── generate-atom-docs.mts         # MDX generator
│   ├── cli.mts                        # Component installer CLI
│   └── sync-shadcn.mts                # Shadcn sync tool
│
├── public/r/                          # Generated registry files
│   ├── styles/
│   │   ├── default/                   # JSON files for all components
│   │   └── new-york/
│   ├── categories.json                # Category list
│   ├── colors/                        # Theme colors
│   └── themes.css                     # Generated theme CSS
│
└── __registry__/
    └── index.tsx                      # Lazy-loaded component index

Key Features Implemented

1. ✅ Registry System (shadcn/ui pattern)

Schema: src/components/root/template/registry.ts

  • Complete Zod validation
  • Support for 14 component types including registry:atom
  • Discriminated unions for file types
  • Full metadata support (dependencies, cssVars, tailwind, etc.)

Atoms Registry: src/registry/default/atoms/_registry.ts

  • 31 atoms categorized
  • Dependencies tracked
  • Registry dependencies mapped
  • Categories: ai, display, animation, interactive, layout, navigation, modal, feedback, data, utility

Build System: scripts/build-registry.mts

  • Generates __registry__/index.tsx with lazy loading
  • Creates JSON files in public/r/styles/{style}/{component}.json
  • Supports both templates and atoms
  • Multi-style support (default, new-york)

2. ✅ Documentation System (fumadocs v16)

31 MDX Files Generated: content/atoms/(root)/*.mdx

  • Frontmatter with categories, dependencies
  • Installation instructions (CLI + Manual)
  • Usage examples
  • API reference tables
  • Accessibility notes

Auto-Generated Sidebar: Updated meta.json

  • All 31 atoms listed alphabetically
  • Integrated with fumadocs page tree
  • Dynamic navigation

Documentation Route: src/app/[lang]/(root)/atoms/

  • Dynamic routing via [[...slug]]
  • Static generation via generateStaticParams()
  • Prev/next navigation
  • Table of contents
  • Breadcrumbs

3. ✅ CLI Tool

Command: pnpm codebase <command>

Available Commands:

pnpm codebase list              # List all components (atoms + templates)
pnpm codebase add <name>        # Install component from registry
pnpm codebase help              # Show help

Features:

  • Fetches components from local registry
  • Installs npm dependencies automatically
  • Resolves registry dependencies recursively
  • Copies files to correct locations
  • Pretty terminal output with emojis

Implementation: scripts/cli.mts

4. ✅ MDX Documentation Generator

Command: pnpm generate:docs

Features:

  • Generates MDX for all atoms automatically
  • Skips existing files
  • Updates meta.json automatically
  • Template-based generation
  • Includes installation, usage, API, accessibility sections

Implementation: scripts/generate-atom-docs.mts

5. ✅ Shadcn/UI Sync Tool

Command: pnpm sync:shadcn

Features:

  • Compares local UI components with shadcn/ui source
  • Detects new, updated, and deleted components
  • Lists available blocks
  • Provides sync recommendations

Configuration:

const SHADCN_PATH = "C:\\Users\\pc\\Downloads\\ui-main\\ui-main\\apps\\v4"

Implementation: scripts/sync-shadcn.mts

6. ✅ Category System

20 Categories:

Template Categories:

  • Sidebar, Dashboard, Authentication, Login, Hero, Charts, Forms, Tables

Atom Categories:

  • AI, Display, Animation, Interactive, Layout, Navigation, Modal, Dialog, UI, Feedback, Data, Utility

File: src/registry/registry-categories.ts

Usage Guide

Adding a New Atom

Option 1: Use CLI

pnpm codebase add infinite-slider

Option 2: Manual

  1. Copy component from registry JSON
  2. Install dependencies manually
  3. Place in src/components/atom/

Creating Documentation for New Atom

  1. Add atom to src/registry/default/atoms/_registry.ts
  2. Run pnpm generate:docs to create MDX
  3. Edit generated MDX in content/atoms/(root)/
  4. Run pnpm build:registry to update registry

Building Registry

pnpm build:registry

This generates:

  • __registry__/index.tsx - Lazy-loaded component index
  • public/r/styles/default/*.json - Component JSON files
  • public/r/styles/new-york/*.json - Style variant JSON files
  • public/r/categories.json - Category mappings
  • public/r/themes.css - Theme CSS variables

Checking Shadcn Updates

pnpm sync:shadcn

Reviews:

  • New UI components from shadcn/ui
  • Updated components (content diff)
  • Deleted components
  • Available blocks

Component Categories

AI Components (7)

  • ai-prompt-input
  • ai-status-indicator
  • ai-streaming-text
  • ai-response-display
  • prompt-input
  • response
  • reasoning

Display/Animation (9)

  • card, card-hover-effect, cards-metric
  • gradient-animation
  • infinite-cards, infinite-slider
  • progressive-blur
  • sticky-scroll
  • simple-marquee

Interactive/Form (3)

  • faceted
  • sortable
  • expand-button

Layout/Navigation (4)

  • header-section
  • page-actions, page-header
  • tabs

Modal/Dialog (1)

  • modal-system (8 files)

UI/Utility (7)

  • loading, announcement
  • two-buttons, agent-heading
  • theme-provider
  • icons, fonts

Templates (8)

  1. dashboard-01 - Analytics dashboard
  2. sidebar-01 - Collapsible sidebar
  3. login-01 - Login form
  4. leads-01 - Lead management
  5. hero-01 - Hero section
  6. header-01 - Header v1
  7. header-02 - Header v2
  8. footer-01 - Footer

Development Workflow

1. Start Development Server

pnpm dev

Visit:

2. Add New Component to Registry

Edit src/registry/default/atoms/_registry.ts:

{
  name: "my-new-atom",
  type: "registry:atom",
  description: "My custom atom component",
  categories: ["display"],
  files: [
    {
      path: "components/atom/my-new-atom.tsx",
      type: "registry:component",
    },
  ],
  registryDependencies: ["button", "card"],
  dependencies: ["framer-motion"],
}

3. Build Registry

pnpm build:registry

4. Generate Documentation

pnpm generate:docs

5. Test CLI

pnpm codebase list
pnpm codebase add my-new-atom

Registry File Format

Example: public/r/styles/default/ai-prompt-input.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "ai-prompt-input",
  "description": "AI-powered prompt input component",
  "type": "registry:atom",
  "dependencies": [],
  "registryDependencies": ["button", "textarea"],
  "files": [
    {
      "path": "components/atom/ai/ai-prompt-input.tsx",
      "content": "// Component source code here",
      "type": "registry:component",
      "target": "components/ai/ai-prompt-input.tsx"
    }
  ],
  "categories": ["ai", "form"]
}

Shadcn/UI Alignment

What We Match

✅ Registry schema structure ✅ Component types (registry:ui, registry:component, registry:block, etc.) ✅ Build system pattern (generate index + JSON files) ✅ Zod validation schemas ✅ Multi-style support ✅ Dependency tracking ✅ CLI pattern (add, list commands)

What We Extend

🔹 Added registry:atom type 🔹 Added 12 new categories for atoms 🔹 Separate atoms registry structure 🔹 MDX documentation generator 🔹 Sync tool for tracking updates 🔹 Fumadocs v16 integration for docs

What We Simplified

📦 No npm package (copy-paste approach) 📦 Local registry only (no remote URLs yet) 📦 Single repository structure 📦 Manual curation vs automated scraping

Statistics

  • UI Components: 50
  • Atoms: 31 (across 12 categories)
  • Templates: 8
  • Total Registry Items: 89
  • MDX Documentation Files: 32 (31 atoms + 1 intro)
  • Categories: 20 (8 template + 12 atom)
  • Build Scripts: 3
  • CLI Commands: 3

Next Steps (Future Enhancements)

Phase 12: Advanced Features

  1. Component Previews

    • Create demo components for each atom
    • Add live preview in documentation
    • Implement code playground

  2. Search Functionality

    • Full-text search across atoms
    • Filter by category
    • Search by dependencies

  3. Remote Registry

    • Host registry on CDN
    • Support remote URLs in CLI
    • Version management

  4. CI/CD Integration

    • Auto-build registry on push
    • Auto-generate docs
    • Deploy to hosting

  5. Enhanced Sync

    • Auto-detect breaking changes
    • Generate migration guides
    • Version tracking

  6. Analytics

    • Track component usage
    • Popular component insights
    • Dependency analysis

Troubleshooting

Registry Build Fails

Issue: Cannot find module '_registry' Solution:

# Ensure registry file exists
ls src/registry/default/atoms/_registry.ts

# Rebuild
pnpm build:registry

CLI Can't Find Component

Issue: Component "X" not found Solution:

# Check if registry is built
ls public/r/styles/default/*.json

# Rebuild if missing
pnpm build:registry

MDX Files Not Generating

Issue: Fumadocs not seeing new files Solution:

# Regenerate fumadocs
pnpm fumadocs-mdx

# Or restart dev server
pnpm dev

Shadcn Sync Fails

Issue: Path not found Solution:

  • Update SHADCN_PATH in scripts/sync-shadcn.mts
  • Ensure shadcn/ui source is downloaded

Credits

  • Inspired by: shadcn/ui
  • Built with:
    • Next.js 16
    • React 19
    • Fumadocs v16
    • Radix UI
    • Tailwind CSS v4
    • Zod
    • TypeScript

License

MIT (following shadcn/ui's open-source philosophy)

Summary

This implementation successfully creates a complete tech paradigm for the "codebase" project that:

  1. ✅ Fully utilizes shadcn/ui's open-source code and patterns
  2. ✅ Organizes 31 atoms + 8 templates + 50 UI components
  3. ✅ Provides comprehensive registry system
  4. ✅ Includes CLI tool for component installation
  5. ✅ Generates documentation automatically
  6. ✅ Tracks shadcn/ui updates
  7. ✅ Maintains 3-layer architecture (UI → Atoms → Templates)
  8. ✅ Follows shadcn/ui best practices

All phases completed successfully! 🎉