Skip to content
Tutorials Center
My learning

Topics

Lesson 52 of 61 ยท Publishing and Maintenance

Migrating Legacy Themes to Online Store 2.0

Upgrade an old Shopify theme: turn Liquid templates into JSON templates, move page code into sections, add section groups, and replace deprecated tags and filters.

Before 2021, only the home page of a Shopify theme could be rearranged in the theme editor. Every other page, such as the product page, used a Liquid template (product.liquid) that merchants could not reorder without a developer. Online Store 2.0 changed that: every page can be built from sections, templates are JSON files that list sections, and apps can add blocks almost anywhere.

A theme written for the old model still works, but it cannot use these features, and it falls behind in tooling and review. This lesson shows what a migration involves, how to plan it, and how to convert a template step by step. It assumes you know JSON Templates and Online Store 2.0, Building a Section and The Theme File Structure.

The theme code, JSON and commands below are real and read-only: this site cannot run a theme. The live example is a JavaScript stand-in that converts a small legacy template into a JSON template. It handles only the simplest case and is there to show the idea, not to replace careful work in your editor.

What changes in a migration

A legacy theme and an Online Store 2.0 theme differ in a few places:

Area Legacy theme Online Store 2.0 theme
Templates templates/product.liquid with page code inside templates/product.json listing sections
Page code In the template In sections such as sections/main-product.liquid
Sections Mostly on the home page On every page
Header and footer Hard-coded in theme.liquid, or fixed sections Section groups you can edit
App UI Pasted into code by developers or app installers App blocks and app embeds
Settings Global values in settings_data.json Same file, plus section settings stored inside each JSON template

The key idea is that a template stops containing markup. It becomes a list: which sections appear on the page, in what order, with which settings. The markup moves into section files. See Layouts and theme.liquid for the part of the page that stays in the layout.

flowchart LR
    subgraph Before
        L["templates/product.liquid<br/>markup + logic"]
    end
    subgraph After
        J["templates/product.json<br/>section list"] --> S1["sections/main-product.liquid"]
        J --> S2["sections/related-products.liquid"]
    end
    L -. "move the code" .-> S1

The code does not disappear. It moves from the template into sections, and the template becomes a table of contents.

Plan the migration

A migration is easier when you do it in a fixed order and keep the store working throughout:

  1. Work on a copy. Duplicate the theme or create a branch and a development theme (see Version Control and Team Workflows). Never convert the live theme.
  2. Run Theme Check. The linter lists deprecated tags and filters before you touch structure (see Theme Check, Linting and Testing).
  3. List every template. Product, collection, page, blog, article, cart, search, 404, customer templates and any alternates such as product.gift.liquid.
  4. Convert one template at a time, starting with the one that matters most (usually the product page). Test it, then move on.
  5. Add section groups for header, footer and announcement bars.
  6. Replace deprecated code.
  7. Test in the editor, not only on the storefront, because the editor is where a migration pays off.

If a template has alternates, such as product.gift.liquid, each alternate becomes its own JSON file (product.gift.json), and merchants assign them to products as before.

Converting a template

Suppose a legacy product.liquid looks like this (read-only):

LIQUID
{% comment %}templates/product.liquid (legacy){% endcomment %}
<div class="product-page">
  <h1>{{ product.title }}</h1>
  <div class="price">{{ product.price | money }}</div>
  {% form 'product', product %}
    <select name="id">
      {% for variant in product.variants %}
        <option value="{{ variant.id }}">{{ variant.title }}</option>
      {% endfor %}
    </select>
    <button type="submit">Add to cart</button>
  {% endform %}
</div>
{% section 'related-products' %}

The conversion has two steps. First, move everything that is page content into a new section file. A section needs a schema tag, even if it is minimal:

LIQUID
{% comment %}sections/main-product.liquid{% endcomment %}
<div class="product-page">
  <h1>{{ product.title }}</h1>
  <div class="price">{{ product.price | money }}</div>
  {% form 'product', product %}
    <select name="id">
      {% for variant in product.variants %}
        <option value="{{ variant.id }}">{{ variant.title }}</option>
      {% endfor %}
    </select>
    <button type="submit">Add to cart</button>
  {% endform %}
</div>

{% schema %}
{
  "name": "Product page",
  "settings": []
}
{% endschema %}

Second, replace the Liquid template with a JSON template that lists the sections. Each key under sections is an ID you choose, type is the section file name without .liquid, and order is the display order:

JSON
{
  "sections": {
    "main": { "type": "main-product", "settings": {} },
    "related": { "type": "related-products", "settings": {} }
  },
  "order": ["main", "related"]
}

Delete the old product.liquid once the JSON template works: keeping both for the same template only causes confusion about which one is used, and Shopify expects one file per template. The name main is a convention: the main content section of a template is called main so that Shopify and apps know which section holds the primary content.

Once the main section works, split it. A monolithic main-product is better than nothing, but the real gain comes when you turn the title, price, form and description into blocks, so merchants can reorder them. That step is described in Blocks and Theme Blocks, and it is where you add {% content_for 'blocks' %} or a loop over section.blocks in the new section.

A stand-in converter

The stand-in below reads a legacy template as text, finds each {% section 'name' %} line, and produces the JSON structure. In a real migration you also move the markup yourself; this tool only automates the list part so you can see the rule.

JS Legacy template to JSON template

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

No output.

Notice that the converter keeps the order of the old {% section %} tags. In the real theme, the markup that stood outside any tag is what you must move into main-product.liquid.

In a legacy theme, the header is often written straight into theme.liquid, or included with {% section 'header' %}. A fixed section can have settings, but the merchant cannot add, remove or reorder the pieces around it. A section group fixes this. It is a JSON file in sections/ whose name ends in -group.json, and it lists sections just like a template does:

JSON
{
  "name": "Header group",
  "type": "header",
  "sections": {
    "announcement": { "type": "announcement-bar", "settings": {} },
    "header": { "type": "header", "settings": {} }
  },
  "order": ["announcement", "header"]
}

In layout/theme.liquid you render the group with the sections tag:

LIQUID
{% sections 'header-group' %}

The same pattern gives you footer-group.json. Merchants can now add an announcement bar above the header in the editor. A section placed in theme.liquid with the single-section {% section 'header' %} tag still works, but it cannot be moved around, so convert it.

Settings and data

The configuration files change little. config/settings_schema.json still defines global settings, and config/settings_data.json still stores the saved values. What you must check is that settings which used to belong to page-level code now live in section schema and that any template reading settings.something still finds it. When you convert templates, copy the values the merchant already chose into the new JSON template's section settings, or the page will lose its configuration.

Back up settings_data.json before you start; see Global Theme Settings: settings_schema.json and settings_data.json.

Replace deprecated code

Migration is the moment to remove old patterns. Theme Check flags most of them:

Old Replace with
{% include 'snippet' %} {% render 'snippet', value: value %} (see Snippets and the render Tag)
| img_url: '600x' | image_url: width: 600 with image_tag
Hard-coded text {{ 'key' | t }} in locale files
product-template.liquid sections that hold page markup Sections under the new template, split into blocks

Replace one pattern at a time and test after each. render isolates variables, so a snippet that relied on the outer scope will break until you pass its inputs explicitly.

A stand-in deprecation scanner

Theme Check finds deprecated code for you, but the idea behind it is simple: look for known patterns line by line. This stand-in scans a snippet for three old patterns and reports each with its line number and a replacement. It is a toy, not Theme Check.

JS Find deprecated Liquid

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a JSON template contain?

    A JSON template is a table of contents. The markup lives in section files that the template names.
  2. 2. What should you do with templates/product.liquid once product.json works?

    Keep one file per template. Move the markup into a section, create the JSON template, and delete the Liquid file.
  3. 3. Why convert the header to a section group?

    A group is a JSON list of sections that the editor can edit, so merchants can add an announcement bar or other sections without code.
  4. 4. After replacing include with render, a snippet suddenly prints empty values. Why?

    render gives the snippet an isolated scope. Pass every value the snippet needs, for example {% render 'card', product: product %}.

Summary

  • Online Store 2.0 means sections on every page, JSON templates, section groups and app blocks.
  • A template becomes a list of sections, and the markup moves into section files with a schema.
  • Keep one file per template: delete the Liquid file after converting.
  • Name the primary section main by convention.
  • Convert header and footer into section groups and render them with {% sections 'header-group' %}.
  • Carry the merchant's existing settings values into the new JSON, and back up settings_data.json first.
  • Replace deprecated tags and filters, remembering that render isolates scope.
  • Migrate on a copy, one template at a time, and test in the editor.

Next, learn how to keep a migrated theme healthy over time in Maintaining Themes: Updates and API Versions.