@digidelv/cli

CLI tool for the DigiDelv design system - automates project initialization, component generation, theme customization, and documentation.

Installation

# Install globally
npm install -g @digidelv/cli

# Or use directly with npx
npx @digidelv/cli init my-app

Commands

digidelv init [project-name]

Initialize a new Next.js project with DigiDelv pre-configured.

Usage:

digidelv init my-app

Interactive Prompts:

• Project name (if not provided as argument)
• Project description (optional)
• Default theme (system/dark/light)
• Neutral color (gray/slate/sand)
• Brand color (14 preset colors including digidelv)
• Accent color (14 preset colors including digidelv)
• Border style (rounded/playful/conservative)
• Include example components (yes/no)
• Install dependencies (yes/no)

Generated Structure:

my-app/
├── app/
│   ├── layout.tsx            # With DigiDelv providers
│   ├── page.tsx              # Homepage with optional examples
│   └── globals.css           # DigiDelv CSS imports
├── components/
│   └── providers.tsx         # ThemeProvider wrapper
├── config/
│   └── digidelv.config.ts    # Theme configuration
├── package.json
├── tsconfig.json
├── next.config.js
└── .gitignore

Example:

# Interactive mode
digidelv init

# With project name
digidelv init my-digidelv-app

# Non-interactive (uses defaults)
digidelv init my-app --no-interactive

digidelv generate component [name]

Alias: digidelv g c [name]

Generate a new component with TypeScript, SCSS module, and MDX documentation.

Usage:

digidelv generate component MyComponent
# or shorter
digidelv g c MyComponent

Interactive Prompts:

• Component name (if not provided as argument)
• Component category (layout/form/display/interactive/media/navigation/custom)
• Component type (client/server)
• Include variants (yes/no) → variant names (comma-separated)
• Include sizes (yes/no) → select sizes (xs/s/m/l/xl)
• Generate SCSS module (yes/no)
• Generate MDX documentation (yes/no)

Generated Files:

packages/core/src/components/
├── MyComponent.tsx           # Component implementation
├── MyComponent.module.scss   # SCSS module (optional)
└── index.ts                  # Updated with new export

apps/docs/src/content/digidelv/components/
└── myComponent.mdx          # Documentation (optional)

digidelv theme create [name]

Create a custom theme with interactive color palette generation.

Usage:

digidelv theme create ocean
# or shorter
digidelv theme create

Interactive Prompts:

• Theme name (if not provided as argument)
• Primary color (hex, e.g., #46e5e8)
• Color generation method (auto/manual)
• Preview palette in terminal (yes/no)
• Add to core package (yes/no)
• Add to function.scss for brand/accent mappings (yes/no)
• Set as default brand color (yes/no)

What it does:

• Generates 12-shade color palette from your primary color
• Creates opacity variants (15%, 30%, 50%)
• Updates scheme.scss with color definitions
• Updates function.scss with brand/accent mappings
• Updates types.ts to include new scheme
• Updates StylePanel.module.scss for theme selector UI
• Optionally sets as default in ThemeProvider

Color Palette Generation: Uses HSL color space to generate a consistent 12-shade palette:

• 100-500: Progressively darker shades
• 600: Your input color (primary)
• 700-1200: Progressively lighter shades
• Automatic saturation adjustment for natural color progression

digidelv theme list (Coming Soon)

List all available theme presets with color previews.

digidelv theme apply <name> (Coming Soon)

Apply a theme to the current project.

digidelv docs generate [component-path]

Auto-generate MDX documentation from component TypeScript file using AST parsing.

Usage:

digidelv docs generate packages/core/src/components/Button.tsx
# or shorter
digidelv docs generate

Interactive Prompts:

• Component file path (if not provided as argument)
• Documentation template (full/minimal)
• Include live preview section (yes/no)
• Include props table (yes/no)
• Include usage examples (yes/no)

What it does:

• Parses TypeScript component file using AST
• Extracts component name and description from JSDoc
• Extracts all props with types and defaults
• Detects variants automatically
• Generates comprehensive MDX documentation
• Creates props table with type information
• Scaffolds code examples based on props

Generated Documentation Includes:

• Component overview and description
• Import statement
• Basic usage example
• Variants section (if applicable)
• Sizes section (if applicable)
• Complete props table with types and defaults
• Usage examples
• Accessibility notes
• Ref forwarding documentation

digidelv validate (Coming Soon)

Validate project structure and configuration.

digidelv upgrade (Coming Soon)

Check for and apply updates to @digidelv/core.

Development

Setup

cd packages/cli
pnpm install
pnpm build

Testing

# Build and test locally
pnpm build
node bin/digidelv.js --help

# Test init command
node bin/digidelv.js init test-project

Project Structure

packages/cli/
├── bin/
│   └── digidelv.js           # CLI entry point
├── src/
│   ├── commands/
│   │   └── init.ts           # Init command implementation
│   ├── utils/
│   │   ├── logger.ts         # Formatted console output
│   │   ├── files.ts          # File system operations
│   │   ├── validators.ts     # Input validation
│   │   ├── prompts.ts        # Inquirer prompts
│   │   ├── template.ts       # Handlebars processing
│   │   └── package-manager.ts # Dependency installation
│   ├── types/
│   │   └── index.ts          # TypeScript interfaces
│   └── index.ts              # CLI setup with Commander
├── templates/
│   └── nextjs-app/           # Next.js App Router template
│       ├── app/
│       ├── components/
│       ├── config/
│       └── *.hbs             # Handlebars templates
├── package.json
├── tsconfig.json
└── README.md

Implementation Status

✅ Phase 1: CLI Foundation (Complete)

• CLI infrastructure with Commander.js
• Utilities (logger, files, validators)
• Type definitions
• Command structure

✅ Phase 2: Project Initialization (Complete)

• digidelv init command
• Interactive prompts with Inquirer
• Handlebars template processing
• Next.js App Router templates
• DigiDelv provider setup
• Dependency installation

✅ Phase 3: Component Generation (Complete)

• digidelv generate component command
• Component templates (TSX, SCSS, MDX)
• Interactive prompts with 8 configuration options
• Handlebars template engine with helpers
• Export barrel automatic updates
• Category-based organization
• Variant and size support
• Optional SCSS module generation
• Optional MDX documentation generation

✅ Phase 4: Theme Customization (Complete)

• digidelv theme create command
• HSL-based color palette generation (12 shades)
• Automatic saturation adjustment for natural progression
• Terminal color preview with ANSI colors
• Chroma.js for color manipulation
• SCSS token file updates (scheme.scss, function.scss)
• TypeScript type updates (types.ts)
• StylePanel.module.scss automatic updates
• ThemeProvider defaults updater
• Brand and accent function mappings
• Opacity variant generation (15%, 30%, 50%)

✅ Phase 5: Documentation Automation (Complete)

• digidelv docs generate command
• TypeScript AST parsing with @typescript-eslint/typescript-estree
• Component name and description extraction
• Prop extraction with types and defaults
• JSDoc comment parsing
• Variant detection from union types
• MDX template generation with Handlebars
• Props table generation with type information
• Code example scaffolding
• Support for forwardRef pattern detection
• Automatic default value extraction
• Full and minimal template options

🚧 Phase 6: Polish & Deployment (Planned)

• Comprehensive testing
• CLI documentation
• Performance optimization
• npm publication

Technologies

• Commander.js - CLI framework with subcommands
• Inquirer.js - Interactive prompts
• Chalk - Terminal styling and colors
• Ora - Terminal spinners
• Handlebars - Template engine
• fs-extra - Enhanced file operations
• execa - Process execution
• TypeScript - Type-safe implementation

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT