How To Migrate a Shopify Theme to Online Store 2.0

Hura Product Showcase Builder

Online Store 2.0 was one of the new features introduced during Shopify Unite 2021.

Online Store 2.0 is a set of features and feature improvements that make themes and theme apps easier to build, more flexible, and more maintainable.

Online Store 2.0 features are available on any development store created after June 29, 2021.

If your account has created before, you can migrate your existing theme to Online Store 2.0. It means you can convert a Liquid template into a JSON template and moving any required Liquid code or HTML into sections that you can include in the new JSON template.

In this article, I will show you how to move the code from a Liquid template file into a section file, and then include that section file in a new JSON template. I’ll also let you know how to add support for app blocks to your sections.

This tutorial uses Debut as an example and moves code from a product.liquid template file into a product-template.liquid section file, which can then be included in a new product.json template.

Please follow the below steps:

Step 1: Back up the theme

Identify the theme that you want to migrate.

After you identify the theme that you want to work on, make a copy of it.

If you’re editing the theme using the code editor, then duplicate the theme. Make sure that the theme is unpublished while you’re editing it. This is because you’ll be removing files from the theme, which would impact the live storefront. You might also need a backup copy to reference or revert to later.

Step 2: Identify sections and remove section references

To start converting your Liquid template into a JSON template, you must make note of and then remove any {% section %} tags.

You need to remove these references so that you can move the rest of the code into a section file. Section files can’t contain references to other section files.

  1. Open your theme in the code editor or your local development environment.
  2. Locate the product.liquid file in the /templates directory.
  3. Search for any {% section %} tags where sections are being included. Note their names and where they are located.
    For example, in Debut, there are two sections included at the top of the template:

    The first section tag references the product-template section, which contains most of the markup needed to render the product page. That includes the product title, product images, add to cart button, and more.
    Next is a reference to the product-recommendations section, which displays a list of products automatically selected as suggestions for customers.

  4. After you’ve found any {% section %} tags and made a note of their location, delete the tags from the product.liquid file.

Step 3: Move code from the template into a section

After you remove the {% section %} tags from the template code, you need to decide where to move it. You can move this code to an existing section or a new section.

Option 1: Add code to an existing section

You might already have a section that renders a large portion of the code for a page. For example, in Debut, the product-template section contains a portion of the code for the product page.

  1. Open the section file where you want to add the template code.
  2. Copy the remaining code from product.liquid.
  3. Paste the code into the section file above the opening {% schema %} tags.

Option 2: Add code to a new section

If none of the existing section files in your theme are appropriate, then you can create a new section to host your Liquid template code.

  1. Create a new file in the /sections directory. For example, product-content.liquid. If you’re creating the section through the code editor, then delete the placeholder code for the section.
  2. After you create your new section file, copy the remaining code from the product.liquid file and paste it into the empty section file.

Step 4: Delete the Liquid template file

After you copy the code from product.liquid, delete product.liquid from the /templates directory. This is because it will be replaced with a product.json file, and a product.liquid and product.json file can’t be stored in the /templates directory at the same time.

Step 5: Create a JSON template file

After the product.liquid file has been deleted, you can create the replacement JSON template.

  1. Create a new file in the /templates directory called product.json:
    • If you’re using the code editor:
      • Select Add a new template.
      • From the Create a template for drop-down menu, choose Product.
      • Select JSON as the template type.
    • If you’re editing the theme locally, then create a new file called product.json and save it in the /templates directory.
  2. After you create the product.json file, replace any default code inside this file with the following:

    The type property should reference the name of the section file where you transferred the markup of the product template file in step 3.

  3. Save the file.

Step 6: Test the template

After you create your new template, open it in the theme editor to make sure that it renders correctly.

Open the theme editor and navigate to a product page. An Add section button should appear in the left sidebar. All the sections that were previously accessible only from the home page should now appear in the Add section menu.

Step 7: Add references to sections

If the original product.liquid template file contained references to additional sections, such as a product recommendations section, then you can define these within the product.json file, and then define their order.

  1. Open product.json. The file currently references only a main section, the section that contains your migrated code.
  2. Add additional sections using this structure. For example, you can add a reference to a product-recommendations section.
    In this example, below the main object, you can insert a second object called recommendations. The type property contains the filename of this section:
  3. Define the order in which the sections appear.
    For example, you can order the recommendation section relative to the main section.
    Within the order array, add recommendations where the section should appear. In this case, the section should appear below the existing <code”>main section.
    After you define the order, your product.json file should look like this:

When you navigate to the theme editor and select a product page, the product recommendations section should now appear on the page below the product template section.

Step 8: Add support for app blocks to sections

If you want to let merchants add app blocks to sections in your theme, then you need to make the following changes to your section code:

Enable app blocks in the section schema

To let merchants add an app block to a section, you need to add blocks of type @app to the section’s schema.

For example, to add support for app blocks to the Debut product-template section, you can add the code below. Because the section doesn’t contain any blocks, you can add a new blocks node after the schema’s settings node.

Render app blocks

To render an app block in your theme, check for the appropriate type, and then render the block using a {% render block %} tag. You can add this code wherever it makes sense for your section.

For example:

Step 9: Repeat the process

You can repeat the process outlined above to convert all of the sections in your theme.

Source: Shopify

Hura Theme Blocks

You may also like...

4 Responses

  1. Pamela says:

    HI! thanks for the tutorial, but i having problems
    I am stuck in this part:
    Create a new file in the / templates directory called product.json:

    If you’re using the code editor:
    Select Add a new template.
    From the Create a template for drop-down menu, choose Product.
    Select JSON as the template type.

    There is no tamplate type option nor does it let me change the liquid ending to Json. this is the eeror then ” File extension is not valid for file templates/product.json, Filename product already exists with liquid extension y Invalid JSON in templates/product.json.”
    What should I do?

  2. Loki says:

    Hi, You can use our automated solution for migration please go to

  3. Sidi Kabba Bakarr says:

    Hi! I was also having problems using the migration instructions on this page. I used your automated solution and it works perfectly. You’re a lifesaver. I will promote your good works in any way I can. Just let me know.

Leave a Reply

Your email address will not be published. Required fields are marked *