@androbinco/library-cli

Interactive CLI tool to add Robin library components to your React project. This tool provides a beautiful, user-friendly interface for selecting and copying components into your project structure.

Description

@androbinco/library-cli is an interactive command-line tool that helps you quickly add pre-built React components to your project. With a modern, Astro-like UI powered by @clack/prompts, you can easily browse and install components with just a few keystrokes.

Installation

Global Installation

npm install -g @androbinco/library-cli

Using npx (without installation)

npx @androbinco/library-cli

Using pnpx (for pnpm users)

pnpx @androbinco/library-cli

Prerequisites

• Node.js (v14 or higher)
• A React project (components require React to function)
• package.json in your project root (recommended for dependency detection)

Quick Start

1. Navigate to your React project directory:

   cd my-react-project

2. Run the CLI:

   npx @androbinco/library-cli

3. Select a component from the interactive menu

4. The component will be copied to src/components/{component-name}/

Usage

Basic Usage

Simply run the CLI from your project root:

robin-library-cli

The CLI will:

1. Display a welcome message with a link to view examples online
2. Check for React dependency in your package.json (warns if not found)
3. Show an interactive menu of available components
4. For components with variants, show a submenu to select specific configurations
5. Copy the selected component to src/components/{component-name}/

Component Structure & Flow

Flow:

1. Main menu (Components or Exit)
2. Components: multiselect prompt — "Please select one or more components"
3. Submenu Selection (for components with variants): Some components offer submenus to select specific variants or configurations
4. Copy selected components (one run can copy many)
5. Post-action prompt: "Do something else?" (loop back to menu) or Exit

Components are copied to the following structure:

your-project/
├── src/
│   └── components/
│       └── {component-name}/
│           └── {component-files}
└── package.json

Overwrite & Safety Behavior

If a component directory already exists:

• Empty directory: The component will be copied without prompting
• Non-empty directory: You'll be prompted to confirm overwrite
  • Select Yes to overwrite existing files
  • Select No to cancel the operation

Additional safety:

• Destination paths are validated to stay inside your current project
• Templates are resolved via ESM-safe import.meta.url

Available Components

Carousel Component

• Name: carousel
• Description: Carousel component with navigation and pagination
• Dependencies: embla-carousel-react, embla-carousel, class-variance-authority
• Files:
  • carousel.barrel.tsx (main component)
  • components/ (navigation buttons, pagination, provider)
  • hooks/ (use-slide-active hook)
  • styles/ (embla.css styles)
  • examples/ (example implementations)
• Location: src/components/carousel/
• Features:
  • Navigation buttons (prev/next)
  • Multiple pagination types (dots, numbers, progress bar)
  • Responsive breakpoints
  • Loop support
  • Slide active state tracking

In-View Component

• Name: in-view
• Description: In view animations for scroll-triggered effects
• Dependencies: motion (Framer Motion)
• Location: src/components/in-view/
• Variants (selectable via submenu):
  • Grid: Grid-based animations
    • Files: in-view-grid.tsx, in-view-animation.tsx, data.in-view.ts
    • Example: in-view-grid-showcase.tsx
  • Individual Elements: Individual element animations
    • Files: in-view-hidden-text.tsx, in-view-stroke-line.tsx, in-view-animation.tsx, data.in-view.ts
    • Example: in-view-examples.home.tsx
• Features:
  • Scroll-triggered animations
  • Grid-based and individual element animations
  • Reusable animation utilities
  • Type-safe data attributes

Ticker Component

• Name: ticker
• Description: Ticker component with hover and non-hover variants
• Dependencies: motion (Framer Motion)
• Location: src/components/ticker/
• Variants (selectable via submenu):
  • Stop on hover ticker (motion): MotionTicker with hover stop functionality
    • Files: motion-ticker.tsx, hooks/ (use-ticker-clones, use-ticker-incremental)
    • Example: ticker-hover-showcase.home.tsx
  • Non-stop on hover ticker (css): TickerStatic with CSS animations
    • Files: css-ticker/css-ticker.tsx, css-ticker/ticker.keyframes.css
    • Example: ticker-static-showcase.home.tsx
• Features:
  • Infinite scrolling ticker
  • Hover to pause (motion variant)
  • CSS-based animation option
  • Customizable speed and direction

Scroll Tracker Component

• Name: scroll-tracker
• Description: Scroll tracker provider for scroll-driven animations
• Dependencies: motion (Framer Motion)
• Files:
  • scroll-tracker-provider.tsx (main provider component)
  • examples/scroll-tracker-showcase.tsx (example implementation)
• Location: src/components/scroll-tracker/
• Features:
  • Scroll progress tracking
  • Context-based scroll state management
  • Enables scroll-driven animations throughout your app
  • Works seamlessly with Framer Motion

More components will be added in future updates.

Features

• ✨ Beautiful, modern UI with Astro-like aesthetics
• 🎯 Interactive component selection
• 🔍 Automatic React dependency detection
• 📦 Automatic dependency installation (detects and installs missing npm packages)
• 🛡️ Safe overwrite handling (checks for empty directories)
• 📁 Automatic directory creation
• ⚠️ Helpful warnings and error messages
• 🚀 Zero configuration required

How It Works

1. Dependency Check: The CLI checks your package.json for React. If not found, it displays a warning but still allows you to proceed (you might add React later).

2. Component Selection: An interactive menu displays all available components with descriptions. You can select multiple components at once. Some components offer submenus to select specific variants or configurations (e.g., Grid vs Individual Elements for in-view animations).

3. Dependency Installation: The CLI automatically detects missing dependencies required by selected components and offers to install them using your project's package manager (npm, pnpm, or yarn).

4. Directory Check: Before copying, the CLI checks if the destination directory exists and whether it's empty.

5. Copy Operation: All files from the component template are copied to src/components/{component-name}/, creating directories as needed.

6. Completion: A success message confirms the component has been added to your project.

Common Use Cases

Adding a Component to a New Project

mkdir my-app && cd my-app
npm init -y
npm install react react-dom
npx @androbinco/library-cli

Adding Multiple Components

Run once and select multiple components in the multiselect:

npx @androbinco/library-cli  # Pick multiple components in one go

Working with Existing Components

If you've modified a component and want to update it:

1. Run the CLI
2. Select the component
3. When prompted about overwriting, choose Yes

Note: This will overwrite your custom changes. Consider backing up your modifications first.

Troubleshooting

"React dependency not found" Warning

This warning appears if React is not listed in your package.json. The CLI will still copy the component, but you'll need to install React for it to work:

npm install react react-dom
# or
pnpm add react react-dom
# or
yarn add react react-dom

"No package.json found" Warning

If you're not in a project directory with a package.json, the CLI will warn you but still allow component installation. Make sure you're in the correct directory.

Permission Errors

If you encounter permission errors, ensure:

• You have write permissions in the current directory
• The src/components/ directory (or its parent) is not read-only

Component Not Appearing

If a component doesn't appear in the selection menu:

• Make sure you're using the latest version of the CLI
• Check that the component template exists in the CLI's templates directory

Development

For contributing to this CLI tool, see the main Robin CLI Tools monorepo.

Local Development

1. Clone the monorepo
2. Install dependencies:

   pnpm install

3. Link the package:

   pnpm --filter @androbinco/library-cli dev

Technical Details

Template Resolution

The CLI uses ESM-compatible path resolution (import.meta.url) to locate templates, ensuring it works correctly when distributed via NPM regardless of where it's installed.

File Operations

• Uses fs-extra for reliable file operations
• Automatically creates nested directories as needed
• Handles file overwrites safely

Error Handling

• Graceful error handling with user-friendly messages
• Non-blocking warnings (dependency checks don't prevent installation)
• Clear cancellation paths

Updating

To update to the latest version:

npm update -g @androbinco/library-cli

Or use npx/pnpx to always get the latest version without global installation.

License

MIT

Support

For issues, questions, or contributions, please refer to the main Robin CLI Tools monorepo.