Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 55 ยท App Extensions

Theme App Extensions

Add your app to a merchant's storefront with theme app extensions: app blocks, app embeds, the Liquid schema, assets and how merchants place them in the theme editor.

For years, apps changed storefronts by editing theme files directly: injecting snippets, patching templates, leaving leftovers behind after uninstall. That approach was fragile, and it made merchants nervous about installing anything. Theme app extensions replace it. Your app ships Liquid, CSS and JavaScript as an extension; the merchant adds it to their theme with a click in the theme editor; and removing the app removes the code cleanly.

This lesson explains the two building blocks (app blocks and app embeds), the {% schema %} that makes them configurable, and how merchants place them. All theme code is read-only here, since it needs a real store and theme. The runnable parts are stand-ins that show how a schema turns merchant settings into output. Read App Extensions Overview first for the extension TOML and deploy model.

Two kinds of building block

App block App embed block
Where it goes Inside a section, at a position the merchant chooses Site-wide, in the <head> or at the end of <body>
Typical use A star rating, a size chart, a "frequently bought together" widget A chat bubble, an analytics script, a cookie banner, a floating button
target in schema "section" "head" or "body"
Merchant enables it in The section's "Add block" menu, under Apps The "App embeds" tab in the theme editor

Because app blocks sit inside sections, the merchant's theme must support them. Online Store 2.0 themes do: their JSON templates let sections accept blocks of type @app. A very old theme without that support gets a different, more manual setup, so check your audience.

Folder layout

A theme app extension is a folder with fixed subfolders. Its TOML is short, because theme extensions have no targets: the files themselves are the interface.

TOML
# extensions/star-rating/shopify.extension.toml
[[extensions]]
type = "theme"
name = "Star rating"
handle = "star-rating"
TEXT
extensions/star-rating/
  shopify.extension.toml
  assets/      CSS, JS and images, served from Shopify's CDN
  blocks/      one .liquid file per app block or app embed
  snippets/    reusable Liquid partials
  locales/     translations for labels and storefront text

Each file in blocks/ is a block. Shopify reads the {% schema %} at the bottom to learn its name, where it can go and what the merchant can configure.

An app block, in Liquid

LIQUID
{%- comment -%} blocks/star-rating.liquid {%- endcomment -%}
<div class="star-rating" {{ block.shopify_attributes }}>
  {%- assign filled = block.settings.stars -%}
  <span class="star-rating__stars" aria-label="{{ filled }} out of 5 stars">
    {%- for i in (1..5) -%}
      {%- if i <= filled -%}&#9733;{%- else -%}&#9734;{%- endif -%}
    {%- endfor -%}
  </span>
  <span class="star-rating__label">{{ block.settings.label }}</span>
</div>

{% schema %}
{
  "name": "Star rating",
  "target": "section",
  "stylesheet": "star-rating.css",
  "settings": [
    { "type": "range", "id": "stars", "label": "Stars", "min": 1, "max": 5, "step": 1, "default": 5 },
    { "type": "text", "id": "label", "label": "Label", "default": "Loved by customers" },
    { "type": "color", "id": "color", "label": "Star color", "default": "#c8860a" }
  ]
}
{% endschema %}

Three things to notice:

  • block.settings.<id> gives your Liquid the merchant's choices. The id in each setting is the key.
  • {{ block.shopify_attributes }} on the root element lets the theme editor select, highlight and reorder the block. Leaving it out is a common bug: the block renders but cannot be clicked in the editor.
  • stylesheet and javascript name files from assets/. Shopify adds the tags to the page only when the block is actually on it, so a page without your block loads none of your code.

Settings use the same input types as theme sections (text, checkbox, range, select, color, image_picker, and more). Each setting needs an id, type and label; a default is strongly recommended so the block looks right the moment it is added.

Which data can the block see?

Liquid objects available depend on where the block sits. A block placed in a product template can use the page's product; one in a footer cannot. If the block needs data from a specific resource, a resource setting such as "type": "product" lets the merchant pick one. Never assume a global exists; guard with {% if product %}.

An app embed

An embed uses "target": "body" (or "head"). It is switched on once for the whole store and has no position in the page.

LIQUID
{%- comment -%} blocks/promo-bar.liquid {%- endcomment -%}
<div class="promo-bar" style="background: {{ block.settings.background }}">
  {{ block.settings.message }}
</div>

{% schema %}
{
  "name": "Promo bar",
  "target": "body",
  "javascript": "promo-bar.js",
  "settings": [
    { "type": "text", "id": "message", "label": "Message", "default": "Free shipping over $50" },
    { "type": "color", "id": "background", "label": "Background", "default": "#1f2937" }
  ]
}
{% endschema %}

Embeds should be light: they can load on every page. Prefer defer or async loading for scripts, and avoid layout shifts.

How merchants place and control them

  1. The merchant installs your app. Your extension is part of the active app version, so it appears in their theme editor.
  2. For an app block: they open a template, choose a section, click Add block, and pick your block under Apps.
  3. For an app embed: they open the App embeds tab and switch it on.
  4. They edit the settings in the sidebar and see the preview update.

Your app can deep-link merchants to the editor with the right block pre-selected, a good "Enable" button for onboarding. Because blocks live in the theme's JSON data, merchants keep their configuration when they change themes only if the new theme supports the same placements, so tell them to re-check after a theme switch.

flowchart TD
  A["App version released"] --> B["Block appears in theme editor"]
  B --> C{"Block target?"}
  C -->|"section"| D["Merchant adds it inside a section"]
  C -->|"head or body"| E["Merchant switches on the App embed"]
  D --> F["Settings saved in theme data"]
  E --> F
  F --> G["Storefront renders Liquid with block.settings"]

Both kinds of block end the same way: merchant choices are stored with the theme and Liquid reads them as block.settings.

A runnable schema renderer

Real rendering happens in Shopify's Liquid engine. This stand-in does the part you can reason about on your own: it takes a block schema plus the settings a merchant saved, applies defaults, rejects invalid values, and fills a simplified template. It is not a Liquid implementation; it only substitutes {{ block.settings.x }} placeholders.

Node.js Resolve schema settings and render a block

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first case shows why defaults matter: a merchant who adds the block and touches nothing still gets something sensible. The last case shows the safety net; in the real editor, range and select inputs cannot produce those values, but data can still be edited by hand or arrive from an older schema version, so build with defaults in mind.

Checking placement

Whether a block can be added to a spot depends on its target and on the section. This second stand-in models that decision with a made-up theme description.

Node.js Where can this block go?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Good practices

  • Give every setting a default and write labels merchants understand.
  • Namespace your CSS classes (star-rating__label) so you do not clash with the theme.
  • Escape output; Liquid escapes with the escape filter, and merchant text must never be treated as HTML.
  • Keep assets small and lazy. A block that hurts page speed gets uninstalled.
  • Support the theme editor: include block.shopify_attributes, and make scripts handle blocks being added or removed live.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which schema target makes a block an app embed that is switched on for the whole store?

    App embeds use target head or body and are enabled from the App embeds tab. The section target is for app blocks placed inside sections.
  2. 2. Why include {{ block.shopify_attributes }} on the block's root element?

    The attributes connect the rendered element to the editor. Without them the block renders but cannot be selected in the editor.
  3. 3. A merchant adds your block and changes nothing. What decides what they see?

    Unset settings fall back to the schema's default values, so good defaults make the block useful immediately.
  4. 4. What is a major advantage of theme app extensions over editing theme files directly?

    Extensions are managed by Shopify and the editor, so installation is a click and removal is clean, unlike code injected into theme files.

Summary

  • Theme app extensions deliver Liquid, CSS and JS as app blocks (inside sections) and app embeds (site-wide in head or body).
  • A block's {% schema %} sets its name, target, assets and merchant-editable settings, read in Liquid as block.settings.<id>.
  • Include block.shopify_attributes for the theme editor and give every setting a default.
  • Assets load only on pages where the block appears; keep them small.
  • Merchants place blocks from the theme editor, so your extension needs no theme file edits and uninstalls cleanly.

Next: Admin UI Extensions