🚀 MVPBlocks CLI

The official command-line interface for MVPBlocks - Copy, paste, customize—and launch your idea faster than ever!

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

✨ 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 (npm, yarn, pnpm, bun)

🎨 Interactive Theme Selection

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

🚀 Intelligent Component System

• Beautiful Terminal UI - Stunning ASCII art and colorful interface
• Smart Search - Find components by name, description, or category
• Auto Dependencies - Automatically installs required packages
• TypeScript & JavaScript - Support for both TS and JS projects
• Organized Structure - Components are organized by type and category
• Lightning Fast - Quick installation and setup

🛠️ Installation

You don't need to install the CLI globally. Use it directly with npx:

npx mvpblocks --help

OR install globally for faster access:

npm install -g mvpblocks
mvpblocks --help

🚀 Quick Start - The Magic Way

1. Start from Scratch (Recommended)

# Navigate to where you want your project
mkdir my-awesome-project
cd my-awesome-project

# Run ANY command and MVPBlocks will set everything up!
npx mvpblocks add hero-1 --ts

What happens automatically:

1. 🔍 Detects empty directory and offers project initialization
2. 🎯 Choose framework: Next.js or Vite + React
3. 🏗️ Creates project using official tools (create-next-app or create-vite)
4. 📦 Installs dependencies with your package manager
5. 🎨 Interactive theme selection - pick from 6 beautiful color palettes
6. 🔧 Sets up Tailwind CSS (v3 for Next.js, v4 for Vite)
7. 📁 Creates component structure and installs your component
8. ✨ Ready to code!

2. Existing Projects

# In your existing React/Next.js project
npx mvpblocks add button
npx mvpblocks add hero-1 --ts

🎨 Auto-Initialization Features

🏗️ Framework Support

• Next.js - Full App Router setup with TypeScript, Tailwind CSS, ESLint
• Vite + React - Lightning-fast development with Tailwind CSS v4

🎨 Theme System

Choose from 6 professionally designed color palettes:

| Theme | Description | 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 |

📦 Package Manager Intelligence

Automatically detects and uses your preferred package manager:

• npm - Default Node.js package manager
• yarn - Fast, reliable, and secure dependency management
• pnpm - Fast, disk space efficient package manager
• bun - Incredibly fast JavaScript runtime and package manager

🔍 Smart CSS Detection

Automatically finds and updates CSS files:

• app/globals.css (Next.js App Router)
• src/globals.css (Next.js with src)
• styles/globals.css (Custom styles folder)
• src/index.css (Vite projects)
• src/main.css (Alternative Vite setup)

📚 Usage

Auto-Initialization Commands

# Start a new project with any component
npx mvpblocks add hero-1 --ts    # Next.js or Vite with TypeScript
npx mvpblocks add button --js    # Next.js or Vite with JavaScript
npx mvpblocks add features       # Auto-detects language preference

Standard Commands

Standard Commands

List all available components

npx mvpblocks list

Add a component to your project

npx mvpblocks add button
npx mvpblocks add hero-1

Search for components

npx mvpblocks search hero
npx mvpblocks search button

View component categories

npx mvpblocks categories

Get detailed component information

npx mvpblocks info button
npx mvpblocks info hero-1

Force language preference

# Force TypeScript
npx mvpblocks add button --ts

# Force JavaScript
npx mvpblocks add button --js

⚡ Live Demo Workflow

Here's what happens when you run MVPBlocks in an empty directory:

mkdir my-project && cd my-project
npx mvpblocks add hero-1 --ts

Interactive Flow:

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

🎯 Commands Reference

| Command | Description | Auto-Init | Example | |---------|-------------|-----------|---------| | add <component> | Add component (auto-initializes if needed) | ✅ | npx mvpblocks add hero-1 --ts | | list | List all available components | ❌ | npx mvpblocks list | | search <query> | Search for components | ❌ | npx mvpblocks search hero | | categories | List all available categories | ❌ | npx mvpblocks categories | | info <component> | Get detailed component information | ❌ | npx mvpblocks info button | | help | Show help message | ❌ | npx mvpblocks help |

🏗️ Project Structure

After Auto-Initialization (Next.js)

my-awesome-project/
├── app/
│   ├── globals.css          # 🎨 Theme applied here
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ui/                  # Basic UI components
│   │   └── button.tsx
│   └── mvpblocks/           # Block components
│       └── hero-1.tsx
├── lib/
│   └── utils.ts             # Utility functions
├── package.json             # 📦 All dependencies
├── tailwind.config.ts       # 🎨 Tailwind setup
└── tsconfig.json           # TypeScript config

After Auto-Initialization (Vite)

my-awesome-project/
├── src/
│   ├── index.css           # 🎨 Theme applied here
│   ├── App.tsx
│   └── main.tsx
├── components/
│   ├── ui/                 # Basic UI components
│   │   └── button.tsx
│   └── mvpblocks/          # Block components
│       └── hero-1.tsx
├── lib/
│   └── utils.ts            # Utility functions
├── package.json            # 📦 All dependencies
├── vite.config.ts          # ⚡ Vite + Tailwind CSS v4
└── tsconfig.json          # TypeScript config

🔧 Options & Flags

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

📋 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 & Setups

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

🎨 Component Types

• UI Components (registry:ui) - Basic building blocks like buttons, inputs, cards
• Block Components (registry:block) - Complete sections like heroes, features, testimonials
• Hooks (registry:hook) - Custom React hooks for enhanced functionality
• Library (registry:lib) - Utility functions and helpers

🚀 Example Workflows

Scenario 1: Complete Beginner

# I want to build a landing page
mkdir my-landing-page
cd my-landing-page
npx mvpblocks add hero-1 --ts
# 🎯 Choose Next.js → Enter project name → Pick theme → Done!
npx mvpblocks add features
npx mvpblocks add testimonials  
npx mvpblocks add cta-1
# Perfect landing page ready! 🚀

Scenario 2: Experienced Developer

# I have specific preferences
mkdir my-saas-app
cd my-saas-app
npx mvpblocks add dashboard --ts
# 🎯 Choose Vite → Modern setup → Blue theme → Ready!
npx mvpblocks add button
npx mvpblocks add modal
# Components added to existing structure

Scenario 3: Existing Project

# Add to my current project  
cd my-existing-project
npx mvpblocks add hero-2
# ✅ Components added directly, no initialization needed

💡 Pro Tips

🎨 Theme Switching

Want to change themes later? Re-run initialization:

npx mvpblocks add button --ts  # Will detect existing project
# 🎨 Theme selection will appear for theme switching

📦 Package Manager Preference

MVPBlocks respects your package manager:

# Will use yarn for everything if yarn.lock exists
yarn create vite my-app
cd my-app  
npx mvpblocks add hero-1  # Uses yarn automatically

🚀 Speed Tips

# Install globally for faster access
npm install -g mvpblocks
mvpblocks add hero-1 --ts  # No npx needed!

🌐 Links

• 🌐 Website: https://blocks.mvp-subha.me
• 📚 Documentation: https://blocks.mvp-subha.me/docs
• 📦 NPM Package: https://www.npmjs.com/package/mvpblocks
• 💻 GitHub: https://github.com/subhadeeproy3902/mvpblocks
• 🐦 Twitter: @mvp_Subha

🎉 What Makes MVPBlocks Special?

🪄 Zero Configuration Magic

Other CLIs require you to set up projects manually. MVPBlocks creates production-ready projects with a single command.

🎨 Professional Theme System

No more tweaking CSS variables manually. Choose from expertly crafted color palettes and get perfect theming instantly.

🚀 Official Tools Integration

Uses create-next-app and create-vite under the hood, ensuring you get the same quality setup as manual creation.

📦 Package Manager Intelligence

Automatically detects and respects your preferred package manager. No configuration needed.

🎯 Smart Defaults

Every choice is optimized for modern development: TypeScript, Tailwind CSS, latest versions, best practices.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas we'd love help with:

• 🆕 New component designs
• 🐛 Bug fixes and improvements
• 📖 Documentation enhancements
• 🧪 Testing and quality assurance

📝 License

MIT License - see the LICENSE file for details.

👨‍💻 Author

Subhadeep Roy

• GitHub: @subhadeeproy3902
• Twitter: @mvp_Subha

🚀 From zero to production-ready in seconds. That's the MVPBlocks promise.

Made with ❤️ for developers who ship fast 🌟