Diari dev: migrazione a un tema Shopify 2.0

Lessons learned: Migrating a theme to Online Store 2.0

Online Store 2.0 has been one of the biggest announcements made at Shopify Unite 2021. It greatly simplified the merchants’ experience with theme customization, as it allows them to create new page, blog and product templates directly from the theme editor, as well as insert sections within these templates.

Many merchants have been on Shopify before this announcement was made, so one of the most common requests we have received recently is to upgrade an existing theme to a 2.0 theme.

Example of sections everywhere

We just completed the first 2.0 theme migration, so I want to take this opportunity to share some of the lessons learned through this experience.

Different approaches

First of all, there are three approaches to add Shopify Online Store 2.0 features to a store:

  1. Download a new version of the current theme
  2. Migrate a theme manually
  3. Choose a new theme

Shopify has a very comprehensive checklist for each one of these options, outlining the advantages and disadvantages of each one.

For those brands not satisfied with their current theme and in need of the 2.0 functionalities, it makes sense to select a new theme altogether. Right now there are 81 themes compatible with the 2.0 Online Store on the Theme Store Shopify.

On the other hand, if they are happy with their current theme, they can choose two paths

The first takes as a starting point a newer version of the theme used by the merchant. Many merchants currently have a theme they purchased from the official Shopify theme store. If this is the case, there is a high chance that the theme developers have already released a 2.0 version of that specific theme, with bug fixes, performance and accessibility optimizations. The merchant can download the latest version of the theme for free from the theme store, and then ask a developer to re-add any custom code to the new version of the theme.

The second approach takes as a starting point the code of the existing theme, where you will convert the all of the templates from .liquid to .json, following the guida ufficiale published by Shopify. As a matter of fact, many of the new features of Online Store 2.0 such as sections everywhere, dynamic data sources or app blocks rely on .json templates, while legacy themes use .liquid templates. In practice, the logic that used to be in the .liquid template will need to be moved to a .liquid section, while the .json template will store the information about the type, order and settings of the sections in that template.

Both approaches are valid and suitable to different types of migration.

In this first project, we decided to opt for the first approach (adding custom code to the new version of the paid theme), because of various reasons related to the state of the legacy code and data restructuring. These are some of the practical points I considered when deciding how to approach the migration:

  • amount of custom code/features added to the original theme
  • leftover code from external unused apps
  • product data restructuring plan (leveraging new metafields, splitting products into color and size variants, collection filters etc.)

One crucial part of this approach is to sit down with the client and list the features needed in the new theme. This was particularly important in our case, since the project also involved optimizing the product data and processes to automate as much as possible and saving time in the day-to-day operation of the store.

Lessons learned

As mentioned, this was our first migration, so it involved some trial and error, especially in the pipeline setup. Of course it’s just the first stepping block and it’s knowledge that will need to be built upon while I apply it to future projects.

Do I really need a development store?

My development process always begins with the setup of a development store, and so that’s what I did for this migration as well. Working on a 2.0 theme migration across two stores involves some extra complexity, especially if you are using the Shopify recommended development tools: Shopify CLI and Github integration.

What I learned is that if the project involves some product data or collection restructuring, I’d recommend setting up a development store, however if it’s a simple theme migration using the same product and page templates, it’s easier to just work on an unpublished theme on the same store.

What are the advantages of working on a development store?

  • You can modify product data without impacting the live site, which continues to run while you are working on the theme migration.
  • You can create new templates and assign them to products or pages by adding them to the published theme. Let’s make a practical example. In our case, we created a new product template specifically for products made to order, which had some logic to display the lead delivery time according to a metafield, and a custom form for height and weight. In the development store we could create the new template available in the admin and assign it to one of the products, so that we could place a test order and make sure the lead time was correctly passed as a line item property and was visible in the order.
  • You can install and test apps that will replace the ones currently being used. For example, we recommended a different translation app and set it up in the development store without any risk of impacting the live store.

If you are working in a development store, you can use an app like Matrixify to import products, collections and files and have data as similar as possible to the live store. Bonus points: Import the images to your test store using the same name, so that they will be recognised also on the live store (more on this in the next point)

Github branching strategies

For this project, I used both the Shopify Theme CLI and the Github integration, which were both introduced at last year’s Shopify Unite. Working with two stores with the Github integration to the same repository is not very straightforward, but the Github integration is super helpful to track all changes made to the code by apps and through the theme editor.

Github integration

To setup the workflow, I logged in the store using the Shopify CLI, downloaded the 2.0 version of the theme using shopify theme pull --theme themeID, uploaded it to Github, and then proceeded to connect one of my branches to the development store.

The staging branch has always been connected to the published theme in the development store, while the main branch has been connected to an unpublished theme in the production store. For the first phase of the development, when I was working on the code without populating the sections through the theme editor, I worked on the different features locally using shopify theme serve, pushed them to the development store using shopify theme push --unpublished, for my teammates to review. So for example I had my feature/cart-changes, branch which, when approved, was then merged to the staging branch which automatically updated the published theme in the dev store.

Once finished working on the skeleton of the theme, we started with the setup of the various templates and sections in the development store. Thanks to the Github integration any changes to the settings and templates were directly pushed to my staging branch.

This is when I merged my staging branch in the main branch - mainly I wanted to check that the newly populated settings were passed on to the a different store. The section settings worked like a charm, even the images which were imported with an identical file name were being displayed correctly in both stores. Of course, the product page could only be checked on the go live day, since the product data could not be modified until that date.

Once ready to publish the new theme to the live store, I stopped merging any changes from staging to the main branch, since I didn’t want to override any of the settings of the live theme with changes made in the development store.

Allocate some time for theme setup and post-launch fixes

Having the main branch connected to an unpublished theme in the live store was helpful to setup those apps that were not installed in the development store, such as Trustpilot or Instagram feed. With the 2.0 theme I was able to add them directly as app blocks, with the settings related to their layout customizable directly from the theme editor.

If you have a multilingual store, allocate some time to test that the new sections’ translations are working correctly for all your languages. I'd pay particular attention to the variant selectors and the color translations in the collection page.

Also, expect the unexpected :-) Some apps add code as soon as the theme is published, and with the Github integration it’s easy to track any change to the code.


Working on my first 2.0 theme migration was an important learning experience, and the Shopify developer documentation as well as the Slack developer community was crucial in outlining all the different options I had as a developer to structure my project.

Have you already completed a 2.0 theme migration and did you do this with the new developer toolkit including Shopify Theme CLI and the Github integration? As always, if you have any feedback, drop me an email at rossella@namastudio.it

Back to blog

Rossella Ferrandino

Rossella is Nama's Front End Developer, so she translates into code your business requirements. She previously worked in events & marketing in London and moved to the tech industry as a self-taught web developer. She is also a volunteer for Women Who Code, a community aimed at empowering women in tech. Her favourite Pokémon is Snorlax.