CascadeKit CLI

A command-line tool for adding Shopify Liquid components from the CascadeKit registry to your theme.

Inspired by shadcn/ui, CascadeKit CLI fetches components on-demand from a remote registry, making it easy to add and manage UI components in your Shopify theme.

Features

• 🌐 Registry-First: Components fetched via HTTP from https://cascadekit.com/r/
• 🔄 Automatic Dependency Resolution: Recursively resolves all component dependencies
• 📦 Smart Package Management: Detects and installs NPM dependencies (supports npm, pnpm, yarn, bun)
• 🎯 Multiple Component Types: Sections, snippets, icons, blocks, and Alpine.js scripts
• 🔍 Search & Discovery: List and search through all available components
• ⚙️ Configurable: Custom paths and multiple registry support

Installation

# Using npx (recommended - no installation needed)
npx cascadekit init

# Or install globally
npm install -g cascadekit
cascadekit init

Quick Start

1. Initialize your theme

cd my-shopify-theme
npx cascadekit init

This creates .cascade/config.json with your preferences.

2. Browse available components

# List all components
npx cascadekit list

# Filter by type
npx cascadekit list --type section

# Search for components
npx cascadekit search cart

3. Add components

# Add a single component
npx cascadekit add mini-cart

# Add multiple components
npx cascadekit add counter product-card hero-slider

4. Check what would change

npx cascadekit diff mini-cart

Commands

cascadekit init

Initialize CascadeKit in your Shopify theme. Creates configuration file and validates theme structure.

npx cascadekit init

Options:

• -y, --yes - Skip prompts and use defaults

cascadekit list

List all available components from the registry.

npx cascadekit list

# Filter by type
npx cascadekit list --type section
npx cascadekit list --type icon

Options:

• -t, --type <type> - Filter by type (section, snippet, icon, block, script)

cascadekit search <query>

Search for components by name, title, description, or tags.

npx cascadekit search hero
npx cascadekit search cart
npx cascadekit search alpine

cascadekit add <components...>

Add one or more components from the registry with all their dependencies.

npx cascadekit add mini-cart
npx cascadekit add counter product-card hero-slider

Options:

• -y, --yes - Skip confirmation prompts
• -o, --overwrite - Overwrite existing files without asking
• -r, --registry <name> - Specify which registry to use

cascadekit diff <component>

Show what files would change when adding a component (dry-run).

npx cascadekit diff mini-cart

cascadekit info <component>

Show detailed information about a component including files, dependencies, and installation status.

npx cascadekit info mini-cart

cascadekit update <components...>

Update installed components to their latest versions.

npx cascadekit update mini-cart
npx cascadekit update counter product-card

Options:

• -y, --yes - Skip confirmation prompts
• -o, --overwrite - Overwrite existing files without asking

cascadekit remove <components...>

Remove installed components from your theme.

npx cascadekit remove mini-cart
npx cascadekit remove counter product-card

Options:

• -y, --yes - Skip confirmation prompts
• -f, --force - Force removal even if other components depend on it

How It Works

CascadeKit CLI uses a registry-first approach:

1. Fetch: Components are fetched from https://cascadekit.com/r/{component}.json
2. Resolve: Registry dependencies are recursively resolved
3. Install: Files are installed according to their type:
   • registry:section → sections/
   • registry:snippet → snippets/
   • registry:icon → snippets/
   • registry:block → blocks/
   • registry:script → src/ (with path preservation, e.g., alpine/store/cart → src/store/cart.ts)
4. Track: Installed components are tracked in .cascade/config.json

Registry Format

Each component in the registry is a JSON file with:

{
  "name": "mini-cart",
  "type": "registry:section",
  "title": "Mini Cart",
  "description": "A compact cart summary...",
  "dependencies": ["alpinejs"],
  "registryDependencies": ["icon-cart", "alpine/store/cart"],
  "files": [
    {
      "name": "mini-cart.liquid",
      "type": "registry:section",
      "content": "..." // Liquid File Content
    }
  ]
}

Configuration

.cascade/config.json example:

{
  "registries": [
    {
      "name": "cascadekit",
      "url": "https://cascadekit.com/r",
      "default": true
    }
  ],
  "paths": {
    "sections": "./sections",
    "snippets": "./snippets",
    "blocks": "./blocks",
    "scripts": "./src"
  },
  "components": {
    "mini-cart": {
      "type": "registry:section",
      "registry": "cascadekit",
      "installedAt": "2025-11-04T12:00:00.000Z",
      "files": ["sections/mini-cart.liquid"],
      "registryDependencies": ["icon-cart", "alpine/store/cart"]
    }
  },
  "cliVersion": "0.1.1"
}

Multi-Registry Support

You can add multiple registries to source components from different locations:

{
  "registries": [
    {
      "name": "cascadekit",
      "url": "https://cascadekit.com/r",
      "default": true
    },
    {
      "name": "custom",
      "url": "https://my-registry.com/components"
    }
  ]
}

Development

# Clone the repository
git clone https://github.com/cleancommit/ui-kit-next.git
cd ui-kit-next/packages/cli

# Install dependencies
pnpm install

# Build the CLI
pnpm build

# Watch mode for development
pnpm dev

# Test locally
node dist/index.js add mini-cart

# Or link globally
npm link
cascadekit add mini-cart

Links

• Website
• Registry
• GitHub
• Issues