Shopify Theme anpassen: Architektur-Guide für Online Store 2.0 (Sections, Liquid, JSON)

1) Architektur festlegen: Was wird im Theme geändert – und was gehört in Apps?

Entscheidungsmatrix (Theme vs. Shopify Apps vs. Custom App)

Bevor du Code anfasst: Lege fest, ob die Anpassung im Theme (Liquid/Sections), über Shopify Apps (App Blocks/Extensions) oder als Custom App (z. B. Admin-Automation) umgesetzt wird. Das schützt dich vor schwer wartbaren Forks und Update-Problemen.

Wo du im Shopify Admin die relevanten Stellen findest

In der Praxis arbeitest du parallel in:

• Shopify Admin → Online Store → Themes (Customizer + Code Editor)
• Shopify Admin → Apps (installierte Shopify Apps + App Blocks im Theme)
• Online Store 2.0 Theme-Architektur: templates/*.json + sections/*.liquid

2) Online Store 2.0 verstehen: Sections, JSON Templates und Update-Sicherheit

Shopify Sections (Konzept)

Shopify Sections sind modulare Bausteine (z. B. Hero, Featured Collection, FAQ), die im Theme Customizer konfigurierbar sind. In Online Store 2.0 werden Sections nicht mehr nur auf der Startseite eingesetzt, sondern können über JSON Templates auf vielen Seitentypen (Produkt, Kollektion, Seite) flexibel zusammengesetzt werden.

Liquid Template Language (Konzept)

Die Liquid Template Language ist Shopifys serverseitige Template-Sprache. Du nutzt Liquid, um:

• Shop-Daten zu rendern (Produkte, Collections, Metafields)
• Section-Settings aus dem Theme Customizer auszulesen
• Blöcke (Blocks) iterierbar zu machen
• HTML strukturiert und sicher auszugeben

Wichtig: Liquid ist Rendering. Business-Logik, Sync und Admin-Automationen gehören in Apps/Backend.

3) Schritt-für-Schritt: Eine eigene Section bauen (Hero/Promo) und im JSON Template verdrahten

Schritt 1: Neue Section-Datei anlegen

Lege unter sections/ eine Datei an, z. B. sections/promo-banner.liquid. Diese Section bekommt Settings (Text, Button, Hintergrund) und optional Blocks (z. B. mehrere USP-Punkte).

Liquid Code for Theme Customization

{% comment %}
  sections/promo-banner.liquid
  Online Store 2.0 section with settings + blocks
{% endcomment %}

<section
  class="promo-banner"
  style="background: {{ section.settings.background_color }};"
  data-section-id="{{ section.id }}"
>
  <div class="page-width">
    {% if section.settings.kicker != blank %}
      <p class="promo-banner__kicker">{{ section.settings.kicker | escape }}</p>
    {% endif %}

    <h2 class="promo-banner__title">
      {{ section.settings.title | escape }}
    </h2>

    {% if section.settings.subtitle != blank %}
      <div class="promo-banner__subtitle">
        {{ section.settings.subtitle }}
      </div>
    {% endif %}

    {% if section.settings.button_label != blank and section.settings.button_url != blank %}
      <a class="button" href="{{ section.settings.button_url }}">
        {{ section.settings.button_label | escape }}
      </a>
    {% endif %}

    {% if section.blocks.size > 0 %}
      <ul class="promo-banner__usp" role="list">
        {% for block in section.blocks %}
          <li class="promo-banner__usp-item" {{ block.shopify_attributes }}>
            {% if block.settings.icon != blank %}
              <span class="promo-banner__usp-icon" aria-hidden="true">{{ block.settings.icon }}</span>
            {% endif %}
            <span class="promo-banner__usp-text">{{ block.settings.text | escape }}</span>
          </li>
        {% endfor %}
      </ul>
    {% endif %}
  </div>
</section>

{% schema %}
{
  "name": "Promo Banner",
  "settings": [
    {
      "type": "text",
      "id": "kicker",
      "label": "Kicker",
      "default": "Neu"
    },
    {
      "type": "text",
      "id": "title",
      "label": "Titel",
      "default": "Winter Sale"
    },
    {
      "type": "richtext",
      "id": "subtitle",
      "label": "Untertitel",
      "default": "<p>Spare bis zu 30% auf ausgewählte Artikel.</p>"
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Hintergrundfarbe",
      "default": "#F6F6F6"
    },
    {
      "type": "text",
      "id": "button_label",
      "label": "Button-Text",
      "default": "Jetzt entdecken"
    },
    {
      "type": "url",
      "id": "button_url",
      "label": "Button-Link"
    }
  ],
  "blocks": [
    {
      "type": "usp",
      "name": "USP",
      "settings": [
        {
          "type": "text",
          "id": "icon",
          "label": "Icon (Text/Emoji)",
          "default": "✓"
        },
        {
          "type": "text",
          "id": "text",
          "label": "Text",
          "default": "Kostenloser Versand ab 49€"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Promo Banner",
      "blocks": [
        { "type": "usp" },
        { "type": "usp" }
      ]
    }
  ]
}
{% endschema %}

Schritt 2: Section in ein JSON Template einhängen

In Online Store 2.0 ist die Seitenstruktur in templates/*.json definiert. Beispiel: du willst das Promo-Banner auf der Startseite im Template templates/index.json hinzufügen.

JSON Config for Shopify Section

{
  "name": "Home",
  "sections": {
    "main": {
      "type": "main-index",
      "settings": {}
    },
    "promo_banner": {
      "type": "promo-banner",
      "blocks": {
        "usp_1": {
          "type": "usp",
          "settings": {
            "icon": "✓",
            "text": "Versand in 1–2 Werktagen"
          }
        },
        "usp_2": {
          "type": "usp",
          "settings": {
            "icon": "✓",
            "text": "30 Tage Rückgabe"
          }
        }
      },
      "block_order": [
        "usp_1",
        "usp_2"
      ],
      "settings": {
        "kicker": "Deal",
        "title": "Nur diese Woche",
        "subtitle": "<p>Spare jetzt auf Topseller.</p>",
        "background_color": "#FFF6E5",
        "button_label": "Angebote ansehen",
        "button_url": "/collections/sale"
      }
    }
  },
  "order": [
    "promo_banner",
    "main"
  ]
}

Schritt 3: Im Theme Customizer testen

Öffne im Shopify Admin den Theme Customizer (Online Store → Themes → Customize), navigiere zur Startseite und prüfe:

• Settings werden korrekt gerendert
• Blocks lassen sich hinzufügen/verschieben
• Richtext-Ausgabe ist gewollt (HTML wird bewusst gerendert)

4) TypeScript in der Theme-Architektur: Stabiler Frontend-Code (ohne Liquid zu überladen)

Wann TypeScript sinnvoll ist

• Interaktive Komponenten (Tabs, Accordions, Sticky Add-to-Cart)
• Sauberes Event-Handling (z. B. Variant-Change Hooks)
• Integration von App Blocks (z. B. Shopify Apps, die DOM-Hooks erwarten)

Beispiel: Section-JS über data-Attribute initialisieren

Pattern: Liquid rendert nur Datenattribute, TypeScript übernimmt Behavior. Das hält die Liquid Template Language schlank und testbar.

TypeScript: Initializer für Promo-Banner Tracking/UX

type PromoBannerConfig = {
  sectionId: string;
  buttonSelector: string;
};

function initPromoBanner(config: PromoBannerConfig): void {
  const root = document.querySelector<HTMLElement>(
    `[data-section-id="${config.sectionId}"]`
  );

  if (!root) return;

  const button = root.querySelector<HTMLAnchorElement>(config.buttonSelector);
  if (!button) return;

  button.addEventListener("click", () => {
    // Example: push to dataLayer; adapt to your analytics setup
    (window as unknown as { dataLayer?: Array<Record<string, unknown>> }).dataLayer ||= [];
    (window as unknown as { dataLayer: Array<Record<string, unknown>> }).dataLayer.push({
      event: "promo_banner_click",
      section_id: config.sectionId,
      href: button.href
    });
  });
}

export function initAllPromoBanners(): void {
  const banners = document.querySelectorAll<HTMLElement>(".promo-banner[data-section-id]");

  banners.forEach((banner) => {
    const sectionId = banner.getAttribute("data-section-id");
    if (!sectionId) return;

    initPromoBanner({
      sectionId,
      buttonSelector: ".button"
    });
  });
}

5) Shopify Apps sauber integrieren: App Blocks statt Theme-Hacks

Warum das architektonisch besser ist

Viele Shopify Apps bringen inzwischen Theme App Extensions mit. Vorteil: Du musst weniger am Theme „herumfrickeln“, Updates sind stabiler und Features lassen sich pro Template/Section steuern.

• App-UI als Block in Sections platzierbar
• Konfiguration im Customizer statt in Code
• Weniger Merge-Konflikte bei Theme-Updates

6) Mermaid: Ziel-Architektur für Theme-Anpassungen

flowchart TD
  A[Shopify Admin] --> B[Theme Customizer]
  B --> C[JSON Templates (Online Store 2.0)]
  C --> D[Sections *.liquid]
  D --> E[Liquid Rendering]
  E --> F[HTML + data-attributes]
  F --> G[TypeScript Behavior]
  A --> H[Shopify Apps]
  H --> I[Theme App Extensions / App Blocks]
  I --> C

7) Release-Checkliste: Damit dein angepasstes Shopify Theme wartbar bleibt

• Trenne Struktur vs. Verhalten: Liquid/Sections für Markup, TypeScript für Interaktion.
• Online Store 2.0 nutzen: JSON Templates statt harter Includes.
• Settings first: Alles, was der Merchant ändern will, als Section Setting/Block modellieren.
• App Blocks bevorzugen: Bei Integrationen mit Shopify Apps nicht direkt in theme.liquid „reinkopieren“.
• Performance: Kein unnötiges JS global laden; lieber pro Section initialisieren.

8) Wenn du’s schneller und update-sicher brauchst

Wenn du Theme-Anpassungen strategisch (Architektur, Performance, Update-Fähigkeit) umsetzen willst, lohnt sich Unterstützung durch eine Shopify Agentur.