How To Migrate Your Theme to Online Store 2.0

How To Migrate Your Theme to Online Store 2.0

Shopify’s Online Store 2.0 is drastically changing the landscape of digital stores. If you’ve been following the evolution of online shopping and the technical aspects behind it, you’ll know that it has been gathering momentum. With Online Store 2.0, themes and theme apps are easier to build than ever before. It is feature-rich, flexible, and simple to maintain. 

This guide will show you how straightforward it is to do this so you can migrate a theme to Online Store 2.0. We’ll show you how to move code from a Liquid template file over to a section file and include this section in a JSON template. We’ll also show you how to add support for app blocks. You can do all these steps using the code editor or Shopify CLI.

What to Expect

Once you’ve migrated your theme to Online Store 2.0, you can use and support several features, including:

  • Sections on every page (not just the homepage!)
  • Dynamic sources
  • App blocks
  • Improved app integration
  • And so much more!

Read our Online Store 2.0 article for a more in-depth look at the features and benefits.

Ready? Don’t Start Yet!

We know this is exciting, but before you get going, do this:

  • Identify the theme you plan to migrate to Online Store 2.0
  • If you want to use your local development environment, install Shopify CLI. The Theme Kit does not support JSON templates.
  • Make sure you have access to the store account or at least have ‘Manage Themes’ permission. If you’re the store owner, this permission will be given to you by default.
  • Note down the store’s URL.

Once you’ve done this, you’re ready to begin the migration. 

9 Steps to Migrate to 2.0 

Shopify 2.0 features mainly rely on JSON templates. To add support for these features, convert a Liquid template into a JSON template and move any Liquid code or HTML into sections so you can include it in the new template. Here’s how:

Step 1 - Back up your theme

Unpublish the theme and make a copy of it. It’s important to unpublish as you’ll be moving files that will impact the storefront. The copy is your backup for reference, or in case you need to roll it back. If you’re using Shopify CLI to edit locally, download the theme files using the theme pull command. 

Step 2 - Identify sections and remove section references

Note down and remove any {% section %} tags. It’s essential to remove these references to move the remainder of the code into a section file, and you can’t have a reference to another section file in a section file. To do this:

  1. Open your theme in the editor or local development environment.
  2. Find the product.liquid file in the /templates directory.
  3. Search for {% section %} tags where sections are included - note the names and locations.
  4. Delete the tags you found from the product.liquid file.

Step 3: Relocate code from the template into sections

After you remove the tags, move the code to a new or existing section. This could be a section that renders a significant portion of code for a page. How to move your code if you have a suitable existing section:

  1. Copy the code from product.liquid. 
  2. Open the section file and paste it above the opening {% schema %} tags.

If you want to add your Liquid template code to a new section, follow these instructions:

  1. Create a new file in the /sections directory.
  2. Copy the code from product.liquid. 
  3. Open the section file and paste it into the new file.

Step 4: Delete the Liquid template file

Once you’ve copied the code, don’t forget to delete product.liquid from the /templates directory. This is because a product.json file will replace it, and the two can’t be stored in the directory simultaneously. 

Step 5: Create the JSON template file to replace the product.liquid file

If you’re editing locally, create a new file called product.json in the /templates directory. If you’re using the code editor:

  1. Add a new template
  2. Click on the ‘Create a template’ drop-down and select ‘Product.’
  3. Select JSON as the template type. 
  4. Save it in the /templates directory.

Once you’ve created the product.json file, replace the default code in it with this code:

{
    "name": "Product",
    "sections": {
       "main": {
           "type": "product-template"
       }
   },
   "order": [
      "main"
   ]
}

Ensure the type property references the name of the section file where you placed the markup of the product template in Step 3. 

Save the file

Step 6: Test your template

Once you’ve created your template, access it in the theme editor to make sure it renders right. You can do this through Shopify CLI by following these steps:

  1. In a terminal, type shopify login --store <DOMAIN> and click the link to log in. 
  2. Access the theme’s working directory. 
  3. Type shopify theme serve. The command will return a link to the Shopify admin theme editor.
  4. Open the editor and navigate to a product page. You should see an ‘Add section’ button to the left in the sidebar. You will no longer need to access sections from the home page; it will now appear in this menu. 

Step 7: Add references to sections

Take note of the original product.liquid template file. If it previously contained references to other sections, you should define them in the product.json file and then define their order. This is how:

  1. Access the product.json file. You’ll notice that it will only reference the code you’ve migrated. 

 {
      "name": "Product",
      "sections": {
          "main": {
              "type": "product-template"   
           }
    },
    "order": [
       "main"
     ]
   }

  1. Use the structure above to add additional sections, for example, a product recommendations section. 
  2. Define the order in which the sections appear.

Your product.json file should look similar to this:

    {
        "name": "Product",
        "sections": {
           "main": {
              "type": "product-template"
            },
            "recommendations": {
               "type": "product-recommendations"
            }
        },
        "order": [
           "main",
           "recommendations"
        ]
    }

You can also use the theme editor to add sections or adjust the order of sections. 

Step 8: Add support for app blocks to sections

You can build app blocks with theme app extensions, which is only available as a preview for developers. If you want to allow merchants to add app blocks to theme sections, make these changes to the section code:

  1. Enable app blocks in the section schema by adding type @app blocks, which are not supported in static sections.
  2. Render app blocks in the theme by checking for the appropriate type and then rendering the block using the tag: {% render block %} Add this code whenever it is relevant to your section. 

Step 9: Repeat 

You can convert all the sections in the theme by repeating the steps above. 

If you get stuck or don’t feel confident about migrating your theme yourself, please give TVP a shout. We are Shopify Experts and can take care of every aspect of your Shopify experience. 

What’s Next?

After you’ve created a new JSON template based on your Liquid template, it would be a good idea to enhance your theme further. Here are some ideas:

  • Draw functionality from the core template code through to sections and blocks to make the template more modular. Read this guide for useful information about dealing with sections and blocks. 
  • Update the theme’s default settings to reference dynamic sources. Find out more about dynamic sources here
  • To simplify theme updates, add version control to your theme by connecting it to a GitHub repository. With this, you can also track changes made across the board. This explains GitHub integration
  • Explore the new suite of developer tools in Online Store 2.0 to help you streamline theme development and testing. Learn more about the newly released tools. 

Yes, You SHOULD Migrate

In case you’re still not 100% certain, it’s a great idea to migrate. Shopify 2.0 makes it so much easier to customize sections; it provides enhanced theme developer tools and quicker loading times. Digital retail is rapidly evolving, and it’s crucial to stay at the forefront. With Online Shop 2.0, you can, and with TVP, the migration process is super easy. Talk to us; we have the answers.

Reading next

Shopify Online Store 2.0 - Even Better Than Brilliant
5 Top eCommerce Trends For 2022