How To Migrate Shopify Themes to Online Store 2.0 (JSON Templates)

Let’s say you have a Shopify store and you’ve been working on it for years. Then, after some time, you’ve taken a look at your Shopify homepage and you’ve decided to customize your Shopify store for a little bit.

But then, BOOM!

You’ve found out that Shopify just recently changed the look of the customizer page and now, you’re lost. So you started reading about it and then you’ve realized that there are new features that you can do.

But, unfortunately, it looks like you can’t do any of the new features (like the “modularity” of the entire Shopify store, app blocks or app extensions, etc.) and that’s because you’re using an old Shopify theme and you need to upgrade it to a JSON template.

So, how can you upgrade your Shopify theme?

Well, in this article we are going to learn how to migrate a Shopify theme from Liquid to Online Store 2.0 (aka JSON templates).

Video Tutorial

If you prefer watching video tutorials, you can watch the following video version of this article.

Otherwise, you can continue below.

Getting Started

Before we get started, I want to point out that we are going to use Debut as an example in this article. We are also going to ONLY show you how to migrate a single template file from Liquid to JSON template and so if you’re looking for an in-depth tutorial about migrating all of the template files to JSON, I highly recommend taking the Shopify Theme Development course. In that course, I will be covering all of the template files from 404 to Search template file.

Also, before we begin, make sure that you BACKUP your Shopify theme. There are a lot of ways to backup a Shopify theme so make sure you do that before doing any of the steps that I will be mentioning in this article.

Migrating Shopify Themes to JSON Templates

You can migrate a Shopify theme in 3 simple steps:

• Identify the sections of your theme templates
• Replace the Liquid template with JSON template
• Test your theme

Looks very simple no? Well, let’s see how to do them.

Identify the sections of your Shopify theme templates

Before you can start migrating your template files from .liquid to a JSON template, you need to make sure that all of the {% section %} tags inside of a template are removed. This is because Shopify doesn’t allow you to use the {% section %} tag inside of a section file and by using a {% section %} tag in a section file, you will receive the following error:

Liquid error (section/section-example.liquid line 58): Cannot render sections inside sections

Once you have found a section tag inside of your section, you have two options:

1. Move the code of that section to the section referencing that section. (Might be confusing but what I mean is merging these sections into one)
2. Create a layout that reference that section.

The second option is quite advanced so to make this article shorter and simple, we’ll just do the first option and so that you get what I’m trying to say in that list.

1. Open your theme code editor
2. Locate a template file (They’re usually inside of the /templates directory). Let’s use the article.liquid in this tutorial.
3. Search for {% section %} tags. (If this is your first time opening that template file, you should be able to find a section tag that references the section named “article-template”).
   
   Did you find one? Great. Remove that section tag and open that “article-template” section file.
   Inside of that section file, you should see a part of the article template that renders the blog post.
   
   So what you’re going to do is to move all of that code to the article.liquid. Because the whole point is to remove all of the section tags from your template.
   
   Now, keep in mind that you should move or paste the code of the “article-template” to the line where the {% section %} tag is located. So if the section tag is located in line 17, then you should paste the code of that section in line 17.
4. Do the same steps for the rest of the section tags that you find.

Replace the old template with JSON template

Now that we have removed the section tags from our template file, we can finally replace this template file with JSON template. But first, we need to move the code of the article.liquid to a section file and then, we can delete the article.liquid and replace it with article.json.

1. Go to /sections directory or folder and create a new section. Name it whatever you what but make sure you remember this name because we’ll use this name in the article JSON template file.
   In my case, I’ll name it template-article.
2. Inside of the template-article.liquid, I’ll move ALL of the code from the article.liquid template file.
3. Delete the article.liquid.
4. Go to /templates directory or folder and create a new template file and select article and make sure that you select JSON instead of Liquid.
5. Once the article.json is created, replace its code with the following:

{
 "sections": {
   "template": {
     "type": "template-article"
   }
 },
 "order": ["template"]
}Code language: JSON / JSON with Comments (json)

Save the file.

Test your Shopify thxeme.

Once you have created your new template, open it with the customizer and check if you can add sections to your article template. If you can, then that means you have successfully migrated your template file from Liquid to JSON template.

Now the next thing that you’re going to do is to apply the same steps to the rest of the template files.

Conclusion

Migrating your Shopify themes from the old template system to Online Store 2.0 is honestly very easy, but it can be very difficult depending on what Shopify theme you’re about to migrate. So my advice, especially if you’re using a different theme, is to learn your Shopify theme first, back it up, and use it with a development store or a test store. That way, your Shopify store is safe from being broken.

We haven’t covered in this article how to use app blocks in JSON template so we’ll probably just cover them in the next video of our YouTube channel. So, if you’re interested, make sure you subscribe to our YouTube channel so we can notify you when we upload a new lesson.