Complete guide to the MVPBlocks CLI - the most intelligent component CLI that auto-initializes projects with themes

🚀 MVPBlocks CLI

The most intelligent component CLI that not only adds components but can automatically initialize entire projects with your preferred framework, theme, and setup.

Zero Configuration Required - MVPBlocks detects empty directories and sets up complete projects automatically!

✨ Revolutionary Features

🪄 Auto-Project Initialization

Zero Configuration - Detects if you're in an empty directory and offers to create a project
Framework Choice - Choose between Next.js or Vite + React
Official Tools - Uses create-next-app and create-vite for rock-solid projects
Package Manager Respect - Automatically detects and uses your preferred package manager

🎨 Interactive Theme Selection

6 Beautiful Color Palettes - Zinc, Red, Rose, Orange, Green, Blue
Smart CSS Detection - Automatically finds and updates your CSS files
Instant Preview - See color swatches before making your choice
Tailwind Integration - Perfect CSS variables setup for light/dark themes

🛠️ Installation

# Use directly (recommended)
npx mvpblocks --help

# Or install globally
npm install -g mvpblocks

# Use directly (recommended)
yarn dlx mvpblocks --help

# Or install globally
yarn global add mvpblocks

# Use directly (recommended)
pnpm dlx mvpblocks --help

# Or install globally
pnpm add -g mvpblocks

# Use directly (recommended)
bunx mvpblocks --help

# Or install globally
bun add -g mvpblocks

🚀 Quick Start - The Magic Way

Auto-Initialization Workflow

Navigate to your project location

mkdir my-awesome-project
cd my-awesome-project

Run ANY component command

npx mvpblocks add hero-1 --ts

yarn dlx mvpblocks add hero-1 --ts

pnpm dlx mvpblocks add hero-1 --ts

bunx mvpblocks add hero-1 --ts

Interactive Setup Begins

🔍 Auto-Detection: "No package.json found. Let's set up a new project!"
🎯 Framework Choice: Choose between Next.js or Vite + React
🏷️ Project Name: Enter your project name (or use current directory)
🚀 Project Creation: Official tools create your project structure
📦 Dependency Installation: All dependencies installed automatically
🎨 Theme Selection: Interactive color palette picker
🔧 Theme Application: CSS variables applied to your theme file
📁 Component Installation: Your requested component is added

🎉 Complete Project Ready!

Your project is now ready with:

✅ Framework setup (Next.js or Vite)
✅ TypeScript/JavaScript configuration
✅ Tailwind CSS integrated
✅ Beautiful theme applied
✅ Component installed and ready to use

🎨 Theme System

Choose from 6 professionally designed color palettes:

Theme	Preview	Perfect For
🔘 Zinc	Modern neutral grays	Professional dashboards, SaaS apps
🔴 Red	Bold and energetic	Marketing sites, calls-to-action
🌹 Rose	Warm and welcoming	E-commerce, lifestyle brands
🟠 Orange	Creative and vibrant	Creative agencies, portfolios
🟢 Green	Fresh and natural	Health, finance, eco-friendly
🔵 Blue	Trust and reliability	Corporate, tech, social platforms

Theme Switching: Want to change themes later? Re-run any component installation and the theme selector will appear!

📚 Commands Reference

`add` - Add Component (with Auto-Init)

The most powerful command that can both initialize projects and add components.

# Basic usage
npx mvpblocks add button

# Force TypeScript (triggers auto-init if needed)
npx mvpblocks add hero-1 --ts

# Force JavaScript (triggers auto-init if needed)
npx mvpblocks add features --js

# Basic usage
yarn dlx mvpblocks add button

# Force TypeScript (triggers auto-init if needed)
yarn dlx mvpblocks add hero-1 --ts

# Force JavaScript (triggers auto-init if needed)
yarn dlx mvpblocks add features --js

# Basic usage
pnpm dlx mvpblocks add button

# Force TypeScript (triggers auto-init if needed)
pnpm dlx mvpblocks add hero-1 --ts

# Force JavaScript (triggers auto-init if needed)
pnpm dlx mvpblocks add features --js

# Basic usage
bunx mvpblocks add button

# Force TypeScript (triggers auto-init if needed)
bunx mvpblocks add hero-1 --ts

# Force JavaScript (triggers auto-init if needed)
bunx mvpblocks add features --js

Example: Adding a hero component to a new project

mkdir landing-page && cd landing-page
npx mvpblocks add hero-1 --ts

mkdir landing-page && cd landing-page
yarn dlx mvpblocks add hero-1 --ts

mkdir landing-page && cd landing-page
pnpm dlx mvpblocks add hero-1 --ts

mkdir landing-page && cd landing-page
bunx mvpblocks add hero-1 --ts

Result: Complete Next.js or Vite project with hero component and theme!

`list` - View All Components

Lists all available components across all categories.

npx mvpblocks list

yarn dlx mvpblocks list

pnpm dlx mvpblocks list

bunx mvpblocks list

Example Output:

📦 UI Components:
  • button - Versatile button component with variants
  • input - Form input with validation states
  • card - Flexible card container component

🧱 Block Components:
  • hero-1 - Modern hero section with CTA
  • features - Feature showcase grid
  • testimonials - Customer testimonials carousel

`search` - Find Components

Search for components by name, description, or category.

npx mvpblocks search hero
npx mvpblocks search button
npx mvpblocks search "landing page"

yarn dlx mvpblocks search hero
yarn dlx mvpblocks search button
yarn dlx mvpblocks search "landing page"

pnpm dlx mvpblocks search hero
pnpm dlx mvpblocks search button
pnpm dlx mvpblocks search "landing page"

bunx mvpblocks search hero
bunx mvpblocks search button
bunx mvpblocks search "landing page"

Example: Searching for hero components

npx mvpblocks search hero

yarn dlx mvpblocks search hero

pnpm dlx mvpblocks search hero

bunx mvpblocks search hero

Example Output:

🔍 Search Results for "hero":

🧱 Block Components:
  • hero-1 - Modern hero section with CTA button
  • hero-2 - Hero with background image and overlay
  • hero-3 - Minimal hero with centered content

`categories` - Browse by Category

View all available component categories.

npx mvpblocks categories

yarn dlx mvpblocks categories

pnpm dlx mvpblocks categories

bunx mvpblocks categories

Example Output:

📂 Component Categories:

📦 UI Components (15 components)
  Basic building blocks like buttons, inputs, cards

🧱 Block Components (25 components)  
  Complete sections like heroes, features, testimonials

🪝 Hooks (8 components)
  Custom React hooks for enhanced functionality

📚 Library (5 components)
  Utility functions and helpers

`info` - Component Details

Get detailed information about a specific component.

npx mvpblocks info button
npx mvpblocks info hero-1

yarn dlx mvpblocks info button
yarn dlx mvpblocks info hero-1

pnpm dlx mvpblocks info button
pnpm dlx mvpblocks info hero-1

bunx mvpblocks info button
bunx mvpblocks info hero-1

Example: Getting button component info

npx mvpblocks info button

yarn dlx mvpblocks info button

pnpm dlx mvpblocks info button

bunx mvpblocks info button

Example Output:

📦 Component: button
📝 Description: Versatile button component with multiple variants and sizes
📂 Category: UI Components
📋 Dependencies: class-variance-authority, @radix-ui/react-slot
🏷️ Registry: registry:ui
📁 File: components/ui/button.tsx

🎨 Variants:
  • default, destructive, outline, secondary, ghost, link
  • Sizes: default, sm, lg, icon

`help` - Show Help

Display help information and available commands.

npx mvpblocks --help
npx mvpblocks help

yarn dlx mvpblocks --help
yarn dlx mvpblocks help

pnpm dlx mvpblocks --help
pnpm dlx mvpblocks help

bunx mvpblocks --help
bunx mvpblocks help

🏗️ Project Structure

Next.js Auto-Initialization

When you run MVPBlocks in an empty directory and choose Next.js:

globals.css

layout.tsx

page.tsx

package.json

tailwind.config.ts

tsconfig.json

Vite Auto-Initialization

When you run MVPBlocks in an empty directory and choose Vite + React:

index.css

App.tsx

main.tsx

package.json

vite.config.ts

tsconfig.json

🎯 Example Workflows

Complete Beginner - Landing Page

Create project directory

mkdir my-landing-page
cd my-landing-page

Add hero section with auto-initialization

npx mvpblocks add hero-1 --ts

yarn dlx mvpblocks add hero-1 --ts

pnpm dlx mvpblocks add hero-1 --ts

bunx mvpblocks add hero-1 --ts

Interactive flow: Choose Next.js → Enter project name → Pick Blue theme → Done!

Add more components

npx mvpblocks add features
npx mvpblocks add testimonials
npx mvpblocks add cta-1

yarn dlx mvpblocks add features
yarn dlx mvpblocks add testimonials
yarn dlx mvpblocks add cta-1

pnpm dlx mvpblocks add features
pnpm dlx mvpblocks add testimonials
pnpm dlx mvpblocks add cta-1

bunx mvpblocks add features
bunx mvpblocks add testimonials
bunx mvpblocks add cta-1

🎉 Perfect landing page ready!

Your complete landing page is now ready with hero, features, testimonials, and CTA sections!

Experienced Developer - SaaS Dashboard

Create SaaS project

mkdir my-saas-app
cd my-saas-app

Initialize with Vite for speed

npx mvpblocks add dashboard --ts

yarn dlx mvpblocks add dashboard --ts

pnpm dlx mvpblocks add dashboard --ts

bunx mvpblocks add dashboard --ts

Interactive flow: Choose Vite → Modern setup → Zinc theme → Ready!

Add UI components

npx mvpblocks add button
npx mvpblocks add input
npx mvpblocks add modal
npx mvpblocks add data-table

yarn dlx mvpblocks add button
yarn dlx mvpblocks add input
yarn dlx mvpblocks add modal
yarn dlx mvpblocks add data-table

pnpm dlx mvpblocks add button
pnpm dlx mvpblocks add input
pnpm dlx mvpblocks add modal
pnpm dlx mvpblocks add data-table

bunx mvpblocks add button
bunx mvpblocks add input
bunx mvpblocks add modal
bunx mvpblocks add data-table

🚀 Production-ready SaaS dashboard!

Complete dashboard with all UI components and proper theming ready for development.

Existing Project - Add Components

Navigate to existing project

cd my-existing-project

Add components directly

npx mvpblocks add hero-2
npx mvpblocks add pricing

yarn dlx mvpblocks add hero-2
yarn dlx mvpblocks add pricing

pnpm dlx mvpblocks add hero-2
pnpm dlx mvpblocks add pricing

bunx mvpblocks add hero-2
bunx mvpblocks add pricing

✅ Components added to existing structure

No initialization needed - components are added directly to your existing project!

💡 Pro Tips

Package Manager Intelligence: MVPBlocks automatically detects your package manager from lock files and uses it consistently throughout the project.

Theme Switching Made Easy

Want to change themes later? Simply re-run any component installation:

npx mvpblocks add button --ts  # Theme selector will appear

yarn dlx mvpblocks add button --ts  # Theme selector will appear

pnpm dlx mvpblocks add button --ts  # Theme selector will appear

bunx mvpblocks add button --ts  # Theme selector will appear

Speed Optimization

Install globally for faster access:

npm install -g mvpblocks
mvpblocks add hero-1 --ts  # No npx needed!

yarn global add mvpblocks
mvpblocks add hero-1 --ts  # No yarn dlx needed!

pnpm add -g mvpblocks
mvpblocks add hero-1 --ts  # No pnpm dlx needed!

bun add -g mvpblocks
mvpblocks add hero-1 --ts  # No bunx needed!

🔧 Options & Flags

Flag	Description	Example
`--ts`, `--typescript`	Force TypeScript output (triggers auto-init if needed)	`--ts`
`--js`, `--javascript`	Force JavaScript output (triggers auto-init if needed)	`--js`
`--help`, `-h`	Show help message	`--help`

📋 Requirements

Node.js 18 or higher
Package Manager: npm, yarn, pnpm, or bun (auto-detected)
No existing setup needed - MVPBlocks creates everything for you!

🎨 Supported Frameworks

Next.js (Auto-Initialized)

✅ App Router with TypeScript
✅ Tailwind CSS v3
✅ ESLint configuration
✅ Automatic globals.css theme integration
✅ Optional src/ directory support

Vite + React (Auto-Initialized)

✅ React with TypeScript/JavaScript
✅ Tailwind CSS v4 with @tailwindcss/vite
✅ Automatic index.css theme integration
✅ Lightning-fast development server

Existing Projects (Manual)

✅ Any React/Next.js project with Tailwind CSS
✅ Components added to existing structure
✅ Dependencies auto-installed

Important: For auto-initialization to trigger, the directory must not contain a package.json file. If you want to initialize in a directory with existing files, temporarily move or rename the package.json.

CLI

🚀 MVPBlocks CLI

✨ Revolutionary Features

🪄 Auto-Project Initialization

🎨 Interactive Theme Selection

🛠️ Installation

🚀 Quick Start - The Magic Way

Auto-Initialization Workflow

🎨 Theme System

📚 Commands Reference

`add` - Add Component (with Auto-Init)

`list` - View All Components

`search` - Find Components

`categories` - Browse by Category

`info` - Component Details

`help` - Show Help

🏗️ Project Structure

Next.js Auto-Initialization

Vite Auto-Initialization

🎯 Example Workflows

Complete Beginner - Landing Page

Experienced Developer - SaaS Dashboard

Existing Project - Add Components

💡 Pro Tips

Theme Switching Made Easy

Speed Optimization

🔧 Options & Flags

📋 Requirements

🎨 Supported Frameworks

Next.js (Auto-Initialized)

Vite + React (Auto-Initialized)

Existing Projects (Manual)

🚀 What Makes MVPBlocks Special?

🪄 Zero Configuration Magic

🎨 Professional Theme System

🚀 Official Tools Integration

📦 Package Manager Intelligence

On this page

Contribute