Skip to main content

App Development - Getting Started

Learn how to create apps that extend O2VEND functionality.

Note: Previously called "Plugins", these are now referred to as "Apps" to better reflect their purpose and align with industry terminology. All functionality remains the same - only the terminology has been updated.

Overview​

Apps (formerly known as plugins) allow you to:

  • Add custom functionality to themes
  • Create payment gateways
  • Integrate third-party services
  • Hook into theme rendering at specific points
  • Extend theme capabilities without modifying core files

App Architecture​

graph TB
    App[App] --> Manifest[app.json<br/>Metadata]
    App --> Hooks[Hooks<br/>Integration Points]
    App --> Assets[Assets<br/>CSS/JS]
    App --> Gateway[Payment Gateway<br/>Optional]
    Hooks --> Theme[Theme Rendering]
    Assets --> Theme
    Gateway --> Payment[Payment Processing]

App Lifecycle​

flowchart TD
    Create[Create App] --> Configure[Configure app.json]
    Configure --> Implement[Implement Hooks]
    Implement --> Test[Test App]
    Test --> Deploy{Deploy?}
    Deploy -->|Yes| Install[Install App]
    Deploy -->|No| Refine[Refine & Iterate]
    Refine --> Test
    Install --> Activate[Activate App]
    Activate --> Runtime[App Running]
    Runtime --> Update{Update?}
    Update -->|Yes| Implement
    Update -->|No| Runtime

App Development Workflow​

flowchart LR
    Start[Start] --> Plan[Plan Functionality]
    Plan --> Create[Create App Structure]
    Create --> Code[Write Code]
    Code --> Test[Test Locally]
    Test --> Validate{Valid?}
    Validate -->|No| Code
    Validate -->|Yes| Package[Package App]
    Package --> Deploy[Deploy]
    Deploy --> Complete[Complete]

App Structure​

An app consists of:

  • app.json - App metadata and configuration (formerly plugin.json)
  • snippets/ - Liquid snippets for hooks
  • assets/ - CSS and JavaScript files
  • gateway.js - Payment gateway implementation (for payment apps)

Example App Structure​

my-app/
  app.json
  snippets/
    hook-theme-head.liquid
    hook-cart-item.liquid
  assets/
    app.css
    app.js
  gateway.js  (optional, for payment apps)

Note: While the file structure uses app.json, you may still see references to plugin.json in older documentation or examples. Both are functionally equivalent.

Quick Start Example​

Step 1: Create App Directory​

mkdir my-first-app
cd my-first-app

Step 2: Create app.json​

{
  "id": "my-first-app",
  "name": "My First App",
  "version": "1.0.0",
  "description": "A simple app example",
  "author": "Your Name",
  "hooks": [
    "theme_head",
    "theme_body_end"
  ]
}

Note: The configuration file can be named app.json or plugin.json - both are supported. We recommend using app.json for new apps.

Step 3: Create Hook Snippet​

Create snippets/hook-theme-head.liquid:

{% comment %}
  Hook: theme_head
  Adds custom CSS to theme head
{% endcomment %}

<link rel="stylesheet" href="{{ 'app.css' | asset_url }}">

Step 4: Create Assets​

Create assets/app.css:

.my-app-custom {
  color: #ff0000;
}

Step 5: Install App​

  1. Copy app to apps/ directory (formerly plugins/)
  2. App will be automatically detected
  3. Activate in theme settings

Common App Types​

1. Theme Enhancement Apps​

Add features to themes:

  • Additional filters
  • Theme modifications
  • Enhanced functionality

2. Payment Gateway Apps​

Integrate payment processors:

  • Stripe
  • PayPal
  • Custom gateways

3. Integration Apps​

Connect third-party services:

  • Analytics
  • Marketing tools
  • Customer support

4. Utility Apps​

Provide utility functions:

  • SEO tools
  • Performance optimization
  • Security enhancements

App Development Checklist​

  • App structure created
  • app.json (or plugin.json) configured
  • Hooks implemented
  • Assets created
  • App tested locally
  • Error handling implemented
  • Documentation written
  • App packaged

Terminology Update​

Important: As of January 2025, "Plugins" have been renamed to "Apps" throughout the system. All functionality remains the same - this is purely a terminology update for clarity and consistency.

  • Old terminology: Plugin, plugin.json, /plugins/ directory
  • New terminology: App, app.json, /apps/ directory

Both old and new terminology work, but we recommend using the new terminology for new projects.

Next Steps​