Shopify 2.0 JSON templates – Vintage Shopify themes rely on monolithic Liquid templates like product.liquid, collection.liquid or page.liquid. Over years of updates and quick fixes, these files accumulate dozens of hard‑coded sections, nested conditionals and copy‑and‑paste code—what developers often describe as spaghetti code. When merchants ask to add a new banner or reorder the product gallery, developers must dive into thousands of lines of markup and risk breaking something unrelated. Worse, these legacy templates can’t take advantage of app blocks or the “sections everywhere” model introduced in Online Store 2.0, so merchants miss out on modular apps and improved site performance. This article explains why modernising your theme matters and how to convert legacy Liquid templates into JSON templates without redesigning your entire storefront.
Why Modernise? Benefits of Online Store 2.0
Shopify’s Online Store 2.0 is more than a UI refresh; it is a new architecture that makes themes more flexible and maintainable. It introduces a JSON template format that stores a list of sections to render. When a page is rendered, the sections are loaded in the order specified by the template, and merchants can add, remove and reorder sections directly from the theme editor. Each JSON template can render up to 25 sections, and each section can have 50 blocks—plenty of space for rich product pages and landing pages. Online Store 2.0 also brings sections on every page, dynamic sources (metafields), and app blocks that let merchants install or update apps without editing theme code. When an app is uninstalled, its code is removed automatically, making themes easier to support.
For merchants, these improvements translate into real advantages: the ability to customise layouts without a developer, reuse sections across pages, and install apps with a few clicks. For developers, JSON templates and app blocks mean cleaner code, easier debugging, and future‑proof themes. A case study of a honey business migrating to Online Store 2.0 showed that refactoring a single product.liquid into multiple JSON templates (product.default.json, product.alternative.json and product.minimal.json) gave the merchant flexible layouts, custom button text, translation support and a cleaner codebase. Importantly, the shopkeeper kept their existing design by simply adding JSON templates and sections, rather than rebuilding the theme from scratch.
Assessing Your Theme
Before refactoring, decide whether to replace, update or migrate your theme. Shopify’s developer documentation notes that you can add Online Store 2.0 functionality in several ways: downloading a new 2.0‑ready theme, updating your theme to its latest version, or migrating manually by converting a Liquid template into a JSON template and moving any required Liquid or HTML into sections. Upgrading isn’t mandatory—if a vintage theme meets your needs you can continue using it—but migrating individual templates is a cost‑effective way to unlock 2.0 features without a redesign.
Consider the following:
Are you satisfied with your theme’s design? If so, a manual migration lets you keep your brand look while modernising the code. If you dislike the design or need new capabilities like Shopify’s drag‑and‑drop sections on every page, a new theme may be more efficient.
Do you use many apps? Themes built for Online Store 2.0 support app blocks, letting you install and uninstall apps without editing code. If your store relies on multiple third‑party apps, migrating unlocks easier integration.
What’s your budget and timeline? Migrating a single product template takes hours or days. Designing and migrating a full theme requires more time and resources.
How Shopify 2.0 JSON templates work in themes
JSON templates are data files stored in the templates/ directory. They contain a sections object that lists which sections to render and an order array that dictates their order. When a page uses a JSON template, Shopify renders each section in the order defined in the template. Because the template is a plain JSON file, the theme editor can programmatically add, remove and reorder sections—no Liquid code is executed. This architecture enables “sections everywhere” and “drag‑and‑drop” editing. It’s important to note that a template can exist either as JSON or Liquid, not both; if product.liquid exists, you cannot create product.json for the same resource.
Step-by-Step: Converting a Liquid Template to Shopify 2.0 JSON templates
The following steps outline how to convert a product.liquid template into a modern JSON template. The same process applies to other templates like collection.liquid or custom page templates.
1. Backup and create a development copy
Always start by duplicating your theme. Work on the duplicate in a staging environment to avoid breaking the live store. Version control (e.g., Git) helps track changes and roll back if needed.
2. Identify and remove section tags
Open product.liquid and look for {% section 'something' %} tags. Each tag injects a section into the page. You need to remove these tags and move the Liquid and HTML code that remains into a new section file. The XgenTech migration guide emphasises taking note of and removing {% section %} tags from the Liquid file, moving the code into section files, and later including those sections in the new JSON template.
3. Create new section files
For each removed section, create a corresponding file under sections/ (for example, main-product.liquid). Copy the relevant markup and logic into this section. At the bottom of the file, add a schema that defines the section’s settings and presets so it appears in the theme editor. To allow apps to render content, add a block definition with { "type": "@app" } and output the content with {% render block %}.
4. Delete the Liquid template
After you’ve moved all the necessary code into sections, delete the original product.liquid file. Shopify’s documentation stresses that Liquid and JSON templates can’t coexist—there can only be one template per resource. Deleting the Liquid file prevents conflicts when Shopify loads the template.
5. Create Shopify 2.0 JSON templates
Create a new file named product.json in the templates/ directory. At minimum, the file should include a name, a list of sections, and the order in which those sections are rendered. For example:
This JSON template tells Shopify to render the main-product section and nothing else. Because the template is JSON, merchants can later add other sections (like related products or trust badges) through the theme editor without editing code.
6.Enable app blocks and dynamic sources in Shopify 2.0 JSON templates
Online Store 2.0 introduces app blocks. To support them, add a block definition in your section’s schema with "type": "@app" and output the block using {% render block %}. You can also use dynamic sources (metafields) to populate product information or custom fields. A dynamic source updates automatically based on context and makes your section reusable across products.
7. Create alternative Shopify 2.0 JSON templates
One of the big wins of JSON templates is the ability to create multiple templates for the same resource. In the honey business case study, developers created product.default.json, product.alternative.json and product.minimal.json to support different layouts and button copy for various products. To create a new template, copy product.json to product.alternative.json and change the sections and order arrays to suit the new layout.
8. Test Shopify 2.0 JSON templates on a staging store
In Shopify Admin, assign the new JSON template to a product and preview it. Confirm that sections render correctly, app blocks work and settings are preserved. Test translations and dynamic content. Once satisfied, publish the updated theme.
The Payoffs: Clean Code & Customisation with Shopify 2.0 JSON templates
Refactoring to JSON delivers immediate benefits:
Cleaner code: By moving each piece of markup into modular sections, you avoid massive conditional statements and duplicated code. Developers can work on individual sections without affecting others.
Flexible layouts: JSON templates let merchants reorder sections, add new ones and create multiple product templates. The honey business case study shows that merchants can choose between default, alternative or minimal layouts for different products. They can also customise button text and translations without modifying code.
App blocks: OS 2.0’s app blocks allow third‑party apps to embed widgets—like reviews, upsell offers or bundle selectors—without editing theme files. When an app is uninstalled, its code is removed automatically.
Future‑proofing: JSON templates align your theme with Shopify’s roadmap. The platform’s documentation notes that migrating individual templates is a supported way to adopt Online Store 2.0 features. Themes using JSON will benefit from future enhancements.
Best Practices & Tips
Work in a staging environment: Never edit your live theme directly. Duplicate the theme, then convert and test changes. Use version control to track modifications.
Convert gradually: Focus on high‑impact templates like product and collection pages first. Migrate one template at a time and ensure each one works before continuing.
Preserve settings: When moving code from Liquid to sections, make sure to replicate the original schema (settings and blocks) so existing configurations carry over. This prevents merchants from losing customisation options.
Communicate with merchants: Let store owners know what will change in the editor. Provide documentation or training on how to add sections, reorder blocks and use app blocks.
Consider design refresh: If your legacy theme looks outdated or relies on unsupported features, consider a full theme upgrade. For many brands, however, modernising the template architecture delivers a strong ROI without a redesign.
Conclusion
Converting spaghetti Liquid code into Shopify 2.0 JSON templates is an investment in maintainability, performance and merchant autonomy. By removing {% section %} tags, moving logic into modular sections, deleting obsolete Liquid files and creating JSON templates, you unlock features like sections on every page, app blocks and dynamic sources. This process doesn’t require a full redesign; you can preserve your brand aesthetic while embracing the future of Shopify theme architecture. If your store relies on hard‑coded templates and you’re frustrated by rigid layouts or messy code, a Theme Modernisation project can deliver immediate flexibility and long‑term benefits. Contact our team to discuss migrating your theme and discover how a little refactoring can make your Shopify store feel brand‑new.
