NuShop CLI

A lightweight CLI for managing reusable Shopify Liquid components

NuShop CLI enables teams to easily publish, discover, and install reusable Shopify Liquid components across multiple projects. Built for developers who want to share sections, snippets, and templates efficiently.

🚀 Quick Start

Get up and running in 3 minutes:

# 1. Install globally
npm install -g nushop

# 2. Set up configuration (you'll need a GitHub token)
nushop config init

# 3. Browse available components
nushop list

# 4. Install a component with dependencies
nushop add product-card

# 5. Publish your own component
nushop publish ./my-component

✨ That's it! Your Shopify components are now installed directly into your theme's directory structure (sections/, snippets/, assets/, etc.) and ready to use!

⚡ v1.1.0 Breaking Change

🎯 New Shopify-First Installation Starting with v1.1.0, components install directly to Shopify theme directories:

# ✅ v1.1.0+ (Shopify-compatible)
nushop add hero-section
# → sections/hero-section.liquid
# → assets/hero-section.css

# ❌ v1.0.x (required manual file moving)
# → components/hero-section/sections/hero-section.liquid
# → components/hero-section/assets/hero-section.css

Migration: If you need the old behavior, use --target ./components

📦 Installation

Global Installation (Recommended)

npm install -g nushop

Local Installation

npm install nushop
npx nushop --help

Requirements

• Node.js 18.0.0 or higher
• Git (for publishing components)
• GitHub account with personal access token

⚙️ Configuration

Before using NuShop CLI, set up your configuration:

nushop config init

This will prompt you for:

• GitHub Token: Personal access token with repository access
• Registry Repository: Default is iwillcodeit/nushop-components
• Default Target: Local directory for installed components (default: . - current directory)

Manual Configuration

Create ~/.nushop/config.json:

{
  "githubToken": "ghp_your_token_here",
  "registryRepo": "iwillcodeit/nushop-components",
  "defaultTarget": "."
}

🔑 GitHub Token Setup

To use NuShop CLI, you need a GitHub Personal Access Token with repository permissions:

Step 1: Generate Token

1. Go to GitHub Settings: Visit github.com/settings/tokens
2. Click "Generate new token" → Select "Generate new token (classic)"
3. Configure the token:
   • Note: "NuShop CLI Access" (or any descriptive name)
   • Expiration: Choose your preferred expiration (90 days recommended)
   • Scopes: Check ✅ repo (Full control of private repositories)
4. Click "Generate token"
5. ⚠️ IMPORTANT: Copy the token immediately - you won't see it again!

Step 2: Configure NuShop

nushop config init
# Paste your token when prompted

Token Requirements

• ✅ repo scope - Required for reading/writing to component registry
• ✅ Access to iwillcodeit/nushop-components - Default registry repository
• ✅ Valid and not expired - Check expiration in GitHub settings

Troubleshooting

• 403 Forbidden: Token lacks repo scope or has expired
• 404 Not Found: Token doesn't have access to the registry repository
• Authentication failed: Token is invalid or malformed

💡 Pro tip: Store your token securely and never commit it to version control!

📖 Commands

nushop list [name]

List available components from the registry.

# List all components
nushop list

# List specific component versions
nushop list hero-section

# JSON output for scripting
nushop list --json

# Verbose output with descriptions
nushop list --verbose

Options:

• --json - Output in JSON format
• --verbose - Show detailed component information

nushop add <name>[@version]

Download and install a component to your project.

# Install latest version
nushop add hero-section

# Install specific version
nushop add [email protected]

# Install to custom directory (e.g., for non-Shopify projects)
nushop add hero-section --target ./my-components

# Skip dependency installation
nushop add product-card --no-deps

# Force reinstall
nushop add hero-section --force

Options:

• --target <dir> - Custom installation directory
• --force - Overwrite existing files
• --no-deps - Skip dependency installation
• --verbose - Show detailed installation process

nushop publish <folder>

Publish a component to the registry.

# Publish component
nushop publish ./my-hero-section

# Dry run (validate without publishing)
nushop publish ./my-component --dry-run

# Force publish (skip warnings)
nushop publish ./my-component --force

# Verbose output
nushop publish ./my-component --verbose

Options:

• --dry-run - Validate component without publishing
• --force - Skip validation warnings
• --verbose - Show detailed publishing process

nushop config

Manage CLI configuration.

# Initialize configuration
nushop config init

# Show current configuration
nushop config show

# Test GitHub token
nushop config test

🏗️ Component Structure

Components follow a standard structure compatible with Shopify themes:

my-component/
├── component.json          # Component manifest (required)
├── sections/              # Shopify sections
│   └── my-section.liquid
├── snippets/              # Shopify snippets
│   └── my-snippet.liquid
├── templates/             # Shopify templates
│   └── my-template.liquid
├── assets/                # CSS, JS, images
│   ├── my-component.css
│   └── my-component.js
└── locales/               # Translation files
    └── en.default.json

Component Manifest (component.json)

Every component must include a component.json file:

{
  "name": "hero-section",
  "version": "1.0.0",
  "description": "A responsive hero section with customizable background and CTAs",
  "keywords": ["hero", "banner", "landing", "shopify"],
  "files": [
    "sections/hero-section.liquid",
    "assets/hero-section.css"
  ],
  "dependencies": {
    "button-snippet": "^1.0.0"
  },
  "author": "Your Name",
  "shopify": {
    "section": true,
    "parameters": ["title", "subtitle", "background_image"]
  }
}

Required Fields:

• name - Component name (kebab-case, 2-50 characters)
• version - Semantic version (e.g., "1.0.0")

Optional Fields:

• description - Component description
• keywords - Array of keywords for discovery
• files - Array of files to include (auto-detected if omitted)
• dependencies - Other components this depends on
• author - Component author
• shopify - Shopify-specific metadata

🔄 Dependency Management

NuShop CLI automatically resolves and installs component dependencies.

Lockfile (nushop-lock.json)

The CLI creates a lockfile to track installed components:

{
  "version": "1.0.0",
  "components": {
    "hero-section": {
      "version": "1.0.0",
      "resolved": "https://github.com/iwillcodeit/nushop-components/tree/main/components/hero-section/1.0.0",
      "dependencies": {}
    },
    "button-snippet": {
      "version": "1.2.0",
      "resolved": "https://github.com/iwillcodeit/nushop-components/tree/main/components/button-snippet/1.2.0",
      "dependencies": {}
    }
  }
}

Version Ranges

Use semantic versioning ranges in dependencies:

• "1.0.0" - Exact version
• "^1.0.0" - Compatible version (>=1.0.0 <2.0.0)
• "~1.0.0" - Patch-level changes (>=1.0.0 <1.1.0)
• "*" - Latest version

🎨 Available Components

Ready-to-use Shopify components in the registry:

🎯 Hero Section ([email protected])

A complete responsive hero section perfect for landing pages.

Features: Background images/videos, text overlays, dual CTAs, multiple heights Files: sections/hero-section.liquid, assets/hero-section.css

nushop add hero-section

🔘 Button Snippet ([email protected])

A versatile button component with multiple styles and states.

Features: 4 styles × 3 sizes, loading states, icons, accessibility features Files: snippets/button.liquid (with inline CSS)

nushop add button-snippet

🛍️ Product Card ([email protected])

An advanced ecommerce product card with rich features.

Features: Image gallery, variants, ratings, wishlist, responsive design Dependencies: Automatically installs button-snippet Files: snippets/product-card.liquid, assets/product-card.css

nushop add product-card  # Installs button-snippet too!

💡 Browse all components: nushop list --verbose

🛠️ Development

Project Structure

nushop-cli/
├── src/                    # TypeScript source code
│   ├── commands/          # CLI command implementations
│   │   ├── add.ts         # Add command
│   │   ├── config.ts      # Config management
│   │   ├── list.ts        # List command
│   │   └── publish.ts     # Publish command
│   ├── lib/               # Core utilities
│   │   ├── github-api.ts  # GitHub API client
│   │   ├── git-repository.ts # Git operations
│   │   └── component-validator.ts # Validation
│   ├── config/            # Configuration management
│   │   └── config-manager.ts
│   ├── types/             # TypeScript definitions
│   └── index.ts           # CLI entry point
├── examples/              # Example components
├── dist/                  # Compiled JavaScript
└── .cursor/rules/         # Development guidelines

Building from Source

# Clone repository
git clone https://github.com/iwillcodeit/nushop-cli.git
cd nushop-cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
node dist/index.js --help

# Development mode with auto-rebuild
npm run dev

Available Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Development mode with watch
• npm run start - Run the CLI
• npm run typecheck - Type checking without compilation
• npm run clean - Clean build artifacts

🧪 Testing

Manual Testing

# Test configuration
nushop config init
nushop config show
nushop config test

# Test component listing
nushop list
nushop list hero-section --verbose

# Test component installation
nushop add button-snippet --dry-run
nushop add button-snippet --target ./test-components

# Test component publishing
nushop publish examples/hero-section --dry-run
nushop publish examples/button-snippet --verbose

Validation Testing

The CLI includes comprehensive component validation:

# Test with example components
nushop publish examples/hero-section --dry-run
nushop publish examples/product-card --dry-run --verbose

🚨 Common Issues & Solutions

🔧 Setup Issues

"Configuration not found"

✗ Configuration not found. Run "nushop config init" to create initial configuration.

Solution: Run nushop config init and provide your GitHub token.

"Authentication failed" Solution: Check your GitHub token has repo scope and isn't expired.

🌐 Network Issues

"Failed to download component" Solutions:

• Check internet connection
• Verify component exists: nushop list component-name
• Try with --verbose for detailed error info

✅ Publishing Issues

"Component validation failed"

✗ Invalid component name. Use kebab-case with letters, numbers, and hyphens only
✗ Invalid version format. Use semantic versioning (e.g., 1.0.0)

Solution: Fix your component.json file according to the error messages.

"Component already exists" Solution: Use --force to overwrite or increment the version number.

🛠️ Debug Mode

Add --verbose to any command for detailed output:

nushop add product-card --verbose
nushop publish ./my-component --verbose

🔒 Security

• Token Security: GitHub tokens are stored locally in ~/.nushop/config.json
• Component Validation: All components are validated before installation
• Dependency Safety: Dependencies are resolved from the same trusted registry
• File Safety: Only Shopify-compatible files are processed

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♀️ Support

Documentation

• Command Reference
• Component Structure
• Examples

Issues

If you encounter any problems, please open an issue with:

• Your operating system and Node.js version
• The command you ran
• The full error message
• Steps to reproduce the issue

Feature Requests

We'd love to hear your ideas! Open an issue with the enhancement label.

🎯 Roadmap

• [ ] Update Command - Update installed components to newer versions
• [ ] Cache Management - Commands to manage local component cache
• [ ] Component Search - Search components by keywords and tags
• [ ] Private Registries - Support for private component registries
• [ ] Component Templates - Generate component boilerplates
• [ ] CI/CD Integration - GitHub Actions for automated publishing
• [ ] Web Dashboard - Browse and manage components via web interface

📊 Stats

• TypeScript: 100% type-safe codebase
• Commands: 4 core commands implemented
• Examples: 3 production-ready component examples
• Validation: Comprehensive component validation system
• Dependencies: Minimal, focused dependency tree

Built with ❤️ for the Shopify developer community