Theme Extension

When to Use

Directory Structure

extensions/theme-extension/
├── blocks/                    # App blocks (merchant can position)
│   ├── feature-block.liquid
│   └── badge.liquid
├── snippets/                  # Reusable Liquid snippets
├── assets/                    # JS/CSS files
└── locales/
    └── en.default.json        # Translations

Liquid-First Rendering

{% comment %} Data from metafields {% endcomment %}
{% assign items = product.metafields.app_namespace.items.value %}

{% if items.size > 0 %}
  <div class="items-list">
    {% for item in items %}
      {% render 'item-card', item: item %}
    {% endfor %}
  </div>
{% else %}
  <p class="no-items">{{ 'app.no_items' | t }}</p>
{% endif %}

Minimal JavaScript Pattern

When JS is Needed

Minimal JS Structure

(function() {
  'use strict';
  const config = window.APP_CONFIG || {};

  function initForms() {
    document.querySelectorAll('[data-app-form]').forEach(form => {
      form.addEventListener('submit', handleSubmit);
    });
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', initForms);
  } else {
    initForms();
  }
})();

Translations

{
  "app": {
    "title": "Feature Title",
    "submit": "Submit",
    "success": "Submitted successfully"
  }
}

{{ 'app.title' | t }}
{{ 'app.count' | t: count: items.size }}

Performance Guidelines

Do's

Don'ts

Checklist

Block Development:
- Schema defines all settings
- Uses snippets for reusable parts
- Translations for all text
- Scoped CSS (no global pollution)
- Minimal/no inline JS

Performance:
- JS deferred or async
- CSS in stylesheet (not inline)
- Images lazy loaded
- No external dependencies
- Bundle < 20KB total