npm package: @o2vend/theme-cli
Description: O2VEND Theme Development CLI - Standalone tool for local theme development
Author: Jeyan Technologies Private Limited
Latest version: 1.0.39

# O2VEND Theme CLI

**Standalone command-line tool for developing O2VEND themes locally.**

The O2VEND Theme CLI is a complete development environment for creating, testing, and packaging O2VEND themes. It works independently and doesn't require access to the main O2VEND webstore solution.

## Prerequisites

- **Node.js 24.0 or later** is required. Download from [nodejs.org](https://nodejs.org/).

## Installation

Install globally via npm:

```bash
npm install -g @o2vend/theme-cli
```

Verify installation:

```bash
o2vend --version
```

## Quick Start

### 1. Get Started with a Theme

**Option A: Use the O2VEND Theme Starter (Recommended)**

Clone the ready-to-use starter template:

```bash
git clone https://github.com/Jeyan-Technologies/o2vend-theme-starter.git
cd o2vend-theme-starter
npm run setup
o2vend serve
```

**Option B: Create a New Theme**

Initialize a new theme from scratch:

```bash
o2vend init my-theme
cd my-theme
o2vend serve
```

### 2. Start Development Server

```bash
o2vend serve
```

This will:
- Start a local development server at `http://localhost:3000`
- Launch a mock API server for testing
- Enable hot reload for instant preview
- Open your browser automatically

## Commands

### `serve`

Start development server with hot reload:

```bash
o2vend serve [options]

Options:
  -m, --mode <mode>           API mode (mock|real) [default: mock]
  -p, --port <port>           Server port [default: 3000]
  --host <host>               Server host [default: localhost]
  -t, --theme <themePath>     Path to theme directory [default: current]
  -e, --env <envFile>         Path to .env file [default: .env]
  --open                       Open browser automatically [default: true]
  --no-open                   Don't open browser
  --mock-api-port <port>      Mock API port [default: 3001]
```

**Examples:**
```bash
# Start in mock mode (default) - works offline
o2vend serve

# Connect to real O2VEND API
o2vend serve --mode real

# Custom port
o2vend serve --port 8080

# Don't open browser automatically
o2vend serve --no-open
```

### `init <name>`

Initialize a new theme project:

```bash
o2vend init my-theme
```

Creates a new theme directory with:
- Complete theme structure (templates, sections, widgets, assets)
- Configuration files (`settings_schema.json`, `settings_data.json`)
- Example templates and widgets
- VS Code configuration
- `.env` file template

### `validate`

Validate theme structure and configuration:

```bash
o2vend validate
```

Checks for:
- Required theme files and directories
- Valid Liquid syntax
- Proper theme structure
- Configuration file validity
- Widget template compatibility

### `check`

Check theme for issues and best practices:

```bash
o2vend check
```

Performs various checks:
- Syntax errors in Liquid templates
- Missing required files
- Performance issues
- Accessibility concerns
- Best practice violations

### `optimize`

Analyze and optimize theme performance:

```bash
o2vend optimize
```

Provides analysis for:
- CSS file sizes
- JavaScript file sizes
- Image optimization opportunities
- Asset bundling recommendations
- Performance metrics

### `package`

Package theme for O2VEND marketplace submission:

```bash
o2vend package [options]

Options:
  -o, --output <path>         Output ZIP file path [default: dist/theme.zip]
  --validate                   Run validation before packaging
  --theme-id <id>             Theme ID for theme.json
  --theme-name <name>         Theme name for theme.json
  --theme-version <version>   Theme version for theme.json
  --author <author>           Author name for theme.json
  --description <description> Theme description for theme.json
```

Creates a marketplace-ready ZIP file with:
- `theme.json` manifest (auto-generated if missing)
- All theme files
- Optional `migrations` folder
- Proper file structure

## Environment Variables

Create a `.env` file in your theme directory:

```env
# API Configuration (for real API mode)
O2VEND_TENANT_ID=your-tenant-id
O2VEND_API_KEY=your-api-key
O2VEND_API_BASE_URL=https://api.o2vend.com

# Development Server
PORT=3000
HOST=localhost
MOCK_API_PORT=3001

# Options
OPEN_BROWSER=true
DEBUG_API_ERRORS=false
```

| Variable | Description | Default |
|----------|-------------|---------|
| `O2VEND_TENANT_ID` | Tenant ID (real mode) | - |
| `O2VEND_API_KEY` | API Key (real mode) | - |
| `O2VEND_API_BASE_URL` | API Base URL (real mode) | - |
| `PORT` | Development server port | `3000` |
| `HOST` | Development server host | `localhost` |
| `MOCK_API_PORT` | Mock API server port | `3001` |
| `OPEN_BROWSER` | Auto-open browser | `true` |
| `DEBUG_API_ERRORS` | Debug API errors | `false` |

## Features

### Hot Reload

Automatic browser refresh on file changes:
- **CSS changes** - Injected without page reload
- **Liquid/JS changes** - Full page reload
- **File watching** - Automatic change detection
- **WebSocket-based** - Real-time updates

### Mock API

Built-in mock API provides realistic test data for offline development:
- Products (20+ sample items)
- Categories (10+ sample items)
- Brands (8+ sample items)
- Widgets (multiple sections: hero, products, footer)
- Store information
- Shopping cart simulation

Perfect for:
- Developing themes without API access
- Testing theme layouts
- Prototyping new designs
- Learning O2VEND theme structure

### Real API Mode

Connect to actual O2VEND Storefront API:
- Full API compatibility
- Authentication support
- Widget loading from API
- Real-time data from your tenant
- Product, category, and brand data

### Theme Structure

O2VEND themes follow a specific structure:

```
theme/
├── layout/
│   └── theme.liquid          # Main layout template
├── templates/
│   ├── index.liquid          # Homepage
│   ├── product.liquid        # Product page
│   ├── collection.liquid    # Collection page
│   └── ...
├── sections/
│   ├── header.liquid
│   ├── footer.liquid
│   └── ...
├── widgets/
│   ├── product.liquid
│   ├── banner.liquid
│   └── ...
├── snippets/
│   └── ...
├── assets/
│   ├── theme.css
│   ├── theme.js
│   └── ...
└── config/
    ├── settings_schema.json
    └── settings_data.json
```

**Important:** Templates, sections, and widgets are **predefined by O2VEND** and come from the O2VEND Storefront API. You can customize existing files but **cannot create new templates, sections, or widget types**.

## Usage Examples

### Development Workflow

```bash
# 1. Start development server
o2vend serve

# 2. Make changes to theme files
# Edit templates, sections, widgets, or assets

# 3. Validate theme structure
o2vend validate

# 4. Check for issues
o2vend check

# 5. Optimize assets
o2vend optimize

# 6. Package for marketplace
o2vend package
```

### Connecting to Real API

```bash
# Create .env file
cat > .env << EOF
O2VEND_TENANT_ID=your-tenant-id
O2VEND_API_KEY=your-api-key
O2VEND_API_BASE_URL=https://api.o2vend.com
EOF

# Start server in real mode
o2vend serve --mode real
```

### Custom Theme Development

```bash
# Create new theme
o2vend init my-custom-theme

# Navigate to theme
cd my-custom-theme

# Start development
o2vend serve

# Customize theme files
# Edit theme/layout/theme.liquid
# Edit theme/templates/index.liquid
# Edit theme/assets/theme.css

# Validate and package
o2vend validate
o2vend package
```

## Theme Development Guidelines

### Customizing Templates

Modify files in `theme/templates/` to change page layouts. For example:
- `templates/index.liquid` - Homepage
- `templates/product.liquid` - Product detail page
- `templates/collection.liquid` - Collection listing page

**Note:** All templates are provided by O2VEND. You can customize them but cannot create new ones.

### Customizing Sections

Modify files in `theme/sections/` to change reusable content blocks:
- `sections/header.liquid` - Site header
- `sections/footer.liquid` - Site footer
- `sections/hero.liquid` - Hero banner section

**Note:** All sections are provided by O2VEND. You can customize them but cannot create new ones.

### Customizing Widgets

Modify files in `theme/widgets/` to change how dynamic content components are rendered:
- `widgets/product.liquid` - Product display widget
- `widgets/banner.liquid` - Banner widget
- `widgets/carousel.liquid` - Carousel widget

**Note:** Widget templates are provided by O2VEND. Widgets themselves are managed through the O2VEND admin panel and loaded via the Storefront API. You can customize widget templates but cannot create new widget types.

### Customizing Assets

Modify files in `theme/assets/` for CSS, JavaScript, and images:
- `assets/theme.css` - Main stylesheet
- `assets/theme.js` - Main JavaScript
- `assets/components.css` - Component styles

## Troubleshooting

### Port Already in Use

```bash
# Use a different port
o2vend serve --port 8080
```

### Layout Not Found Error

Make sure your templates use the correct layout path:
```liquid
{% layout 'layout/theme' %}
```

The layout file should be at: `theme/layout/theme.liquid`

### API Connection Issues

If using real API mode:
1. Verify `.env` file has correct credentials
2. Check API base URL is correct
3. Ensure tenant ID and API key are valid
4. Try mock mode first: `o2vend serve --mode mock`

### Hot Reload Not Working

1. Check browser console for WebSocket errors
2. Verify firewall isn't blocking WebSocket connections
3. Try refreshing the page manually
4. Restart the server: `o2vend serve`

## Support & Resources

- **[O2VEND Developer Documentation](https://o2vend.com/developer/)** - Complete API documentation and guides
- **Support Email:** support@o2vend.com or developer@jeyantechnologies.com
- **Support Desk:** [O2VEND Support Portal](https://o2vend.atlassian.net/servicedesk/customer/portals)
- **Community:** [O2VEND Community Program](https://o2vend.com/community)
- **Partnership:** [O2VEND Partnership Program](https://o2vend.com/partnership)
- **Developer Portal:** [www.o2vend.com](https://www.o2vend.com)

## Related Tools

- **[O2VEND Theme Starter](https://github.com/Jeyan-Technologies/o2vend-theme-starter)** - Ready-to-use starter template with complete default theme
- **[O2VEND Liquid VS Code Extension](https://marketplace.visualstudio.com/items?itemName=O2VEND.o2vend-liquid)** - Syntax highlighting and IntelliSense for O2VEND Liquid templates

## License

MIT License - See LICENSE file

---

**Ready to build amazing O2VEND themes?** Start with the [O2VEND Theme Starter](https://github.com/Jeyan-Technologies/o2vend-theme-starter) or create your own with `o2vend init`!