Skip to main content

Create Your First Theme

This tutorial will guide you through creating your first O2VEND theme from scratch.

Prerequisites​

  • Basic knowledge of HTML, CSS, and JavaScript
  • Understanding of Liquid template syntax
  • Access to O2VEND storefront
  • Node.js installed (for CLI)
  • VS Code with O2VEND Liquid extension (recommended)

Step 1: Install Development Tools​

Install O2VEND Theme CLI​

npm install -g @o2vend/theme-cli
  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "O2VEND Liquid"
  4. Click Install

Step 2: Create Theme Structure​

The easiest way is to use the CLI to initialize your theme:

o2vend init my-first-theme
cd my-first-theme

This creates a complete theme structure with all necessary files and folders.

Option B: Manual Creation​

If you prefer to create the structure manually:

mkdir my-first-theme
cd my-first-theme
mkdir -p layout templates sections snippets assets config

The structure should look like:

my-first-theme/
  layout/
    theme.liquid
  templates/
    index.liquid
  assets/
    theme.css
    theme.js
  config/
    settings_schema.json
    settings_data.json

Step 3: Create Main Layout​

Create layout/theme.liquid:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ page_title | default: shop.name }}</title>
  
  {{ 'theme.css' | asset_url | stylesheet_tag }}
</head>
<body>
  {% section 'header' %}
  
  <main>
    {{ content }}
  </main>
  
  {% section 'footer' %}
  
  {{ 'theme.js' | asset_url | script_tag }}
</body>
</html>

Step 4: Create Homepage Template​

Create templates/index.liquid:

{% layout 'theme' %}

<section class="hero">
  <h1>Welcome to {{ shop.name }}</h1>
  <p>{{ shop.description }}</p>
  <a href="/collections/all" class="btn">Shop Now</a>
</section>

<section class="featured-products">
  <h2>Featured Products</h2>
  <div class="product-grid">
    {% for product in collections.featured.products limit: 4 %}
      {% render 'product-card', product: product %}
    {% endfor %}
  </div>
</section>

Step 5: Create Product Card Snippet​

Create snippets/product-card.liquid:

<div class="product-card">
  <a href="{{ product | product_url }}">
    <img 
      src="{{ product.featured_image | img_url: 'medium' }}" 
      alt="{{ product.name }}"
    >
    <h3>{{ product.name }}</h3>
    <p class="price">{{ product.price | money }}</p>
  </a>
</div>

Step 6: Create Header Section​

Create sections/header.liquid:

<header class="site-header">
  <div class="header-container">
    <div class="logo">
      <a href="/">{{ shop.name }}</a>
    </div>
    <nav>
      <a href="/collections/all">Shop</a>
      <a href="/cart">Cart</a>
    </nav>
  </div>
</header>

Create sections/footer.liquid:

<footer class="site-footer">
  <div class="footer-container">
    <p>&copy; {{ 'now' | date: '%Y' }} {{ shop.name }}. All rights reserved.</p>
  </div>
</footer>

Step 8: Add Basic Styles​

Create assets/theme.css:

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: Arial, sans-serif;
  line-height: 1.6;
}

.site-header {
  background: #000;
  color: #fff;
  padding: 1rem;
}

.header-container {
  max-width: 1200px;
  margin: 0 auto;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.logo a {
  color: #fff;
  text-decoration: none;
  font-size: 1.5rem;
  font-weight: bold;
}

nav a {
  color: #fff;
  text-decoration: none;
  margin-left: 1rem;
}

.hero {
  text-align: center;
  padding: 4rem 2rem;
  background: #f5f5f5;
}

.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 2rem;
  padding: 2rem;
  max-width: 1200px;
  margin: 0 auto;
}

.product-card {
  border: 1px solid #ddd;
  border-radius: 8px;
  overflow: hidden;
  transition: transform 0.3s;
}

.product-card:hover {
  transform: translateY(-5px);
}

.product-card img {
  width: 100%;
  height: auto;
}

.product-card h3 {
  padding: 1rem;
  margin: 0;
}

.product-card .price {
  padding: 0 1rem 1rem;
  font-weight: bold;
  color: #000;
}

.btn {
  display: inline-block;
  padding: 0.75rem 1.5rem;
  background: #000;
  color: #fff;
  text-decoration: none;
  border-radius: 4px;
  margin-top: 1rem;
}

.site-footer {
  background: #333;
  color: #fff;
  text-align: center;
  padding: 2rem;
  margin-top: 4rem;
}

Step 9: Add Basic JavaScript​

Create assets/theme.js:

document.addEventListener('DOMContentLoaded', function() {
  console.log('Theme loaded');
  
  // Add any interactive functionality here
});

Step 10: Create Settings Schema​

Create config/settings_schema.json:

{
  "sections": [
    {
      "name": "Theme Settings",
      "settings": [
        {
          "type": "text",
          "id": "primary_color",
          "label": "Primary Color",
          "default": "#000000"
        }
      ]
    }
  ]
}

Step 11: Test Your Theme Locally​

Using the CLI Development Server​

Start the development server to preview your theme locally:

# From your theme directory
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

You can now:

  • View your theme in the browser
  • Make changes and see them instantly
  • Test different pages and features
  • Check responsive design

Deploy to O2VEND Store​

When you're ready to deploy:

  1. Package your theme:

    o2vend package

  2. Upload the generated ZIP file to your O2VEND store

  3. Activate the theme

  4. Visit your storefront

  5. Test all pages

  6. Check responsive design

Next Steps​

  • Add more templates (product, collection, cart)
  • Create more snippets
  • Add widgets
  • Customize styling
  • Add JavaScript functionality

Troubleshooting​

Theme Not Loading​

  • Check file structure
  • Verify Liquid syntax
  • Check browser console
  • Ensure layout file exists at layout/theme.liquid

Styles Not Applying​

  • Verify CSS file path
  • Check asset URLs (use asset_url filter)
  • Clear browser cache
  • Check that CSS file is in assets/ directory

CLI Server Not Starting​

  • Check that port 3000 is available
  • Verify Node.js is installed
  • Try a different port: o2vend serve --port 8080
  • Check for error messages in the terminal

Hot Reload Not Working​

  • Check browser console for WebSocket errors
  • Verify firewall isn't blocking WebSocket connections
  • Try refreshing the page manually
  • Restart the server: o2vend serve

Congratulations!​

You've created your first O2VEND theme! Continue learning: