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.

Installation

Install globally via npm:

npm install -g @o2vend/theme-cli

Verify installation:

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:

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:

o2vend init my-theme
cd my-theme
o2vend serve

2. Start Development Server

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:

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:

# 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:

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:

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:

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:

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:

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:

# 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

# 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

# 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

# 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

# Use a different port
o2vend serve --port 8080

Layout Not Found Error

Make sure your templates use the correct layout path:

{% 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 - Complete API documentation and guides
• Support Email: [email protected] or [email protected]
• Support Desk: O2VEND Support Portal
• Community: O2VEND Community Program
• Partnership: O2VEND Partnership Program
• Developer Portal: www.o2vend.com

Related Tools

• O2VEND Theme Starter - Ready-to-use starter template with complete default theme
• O2VEND Liquid VS Code Extension - 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 or create your own with o2vend init!