AI-Assisted Shopify Theme Migration: A Complete Playbook

Key takeaways

• A Shopify theme migration moves a store from one theme to another. Moving a vintage theme to Online Store 2.0 means rebuilding it, not copying files across.
• Vintage themes and Online Store 2.0 themes use different template formats. Liquid templates become JSON templates, and custom code has to move into sections.
• Metafields and metaobjects live in your store data, not the theme. They survive the move, but the dynamic source connections that display them are theme-side and need reconnecting.
• Do every step on a duplicated, unpublished theme. Shopify’s own migration docs start with this.
• AI handles the repetitive translation work - rewriting Liquid, splitting monolithic templates into sections, porting CSS and JS - while you keep the audit, mapping, and testing.

A Shopify theme migration is the process of moving a store from one theme to another inside Shopify. This guide covers the hardest version of that job: taking a vintage (pre-2021) theme and moving it to an Online Store 2.0 theme such as Dawn, or replacing an aging base theme with a modern one. This is theme-to-theme work inside Shopify. It is not a platform migration from WooCommerce or Magento.

The reason this migration is hard is structural. Online Store 2.0 changed how themes are built. Shopify launched it on June 29, 2021, introducing JSON templates and app blocks so merchants can add, remove, and reorder sections on most pages, not just the home page.¹ A vintage theme cannot be upgraded in place. You rebuild it on the new architecture, then move your customizations across.

This playbook walks through the full sequence: auditing the old theme, mapping sections and settings, using AI (Claude) to translate custom Liquid, CSS, and JS into the new theme’s structure, preserving metafields and templates, testing on an unpublished theme, and keeping a rollback path open the whole time.

Why you can trust us

Jacques has over 15 years of development experience and has worked with hundreds of Shopify stores. We built Fudge - an AI-native Shopify page builder and store editor with a 5.0 rating and a Built for Shopify badge. Theme migrations, section mapping, and Liquid rewrites are the daily work behind the product.

What changes between a vintage theme and Online Store 2.0

Before you touch any code, understand what actually differs. The gap between the two architectures is the reason a migration is a rebuild.

A JSON template is a data file. It stores a list of sections to render and their settings, and merchants manage those sections in the theme editor.² Each JSON template can render up to 25 sections, each section can hold up to 50 blocks, and a theme can hold up to 1,000 JSON templates.² Those limits shape how you split an old monolithic template.

The most important structural rule: section files cannot reference other section files.⁴ Vintage templates that stack multiple {% section %} tags have to be flattened, because the code inside each new section must be self-contained.

Step 1: Audit the old theme

You cannot migrate what you have not catalogued. Start with a full inventory of the theme you are leaving.

Work through the theme files and record:

1. Every custom template - product, collection, page, blog, and any alternate templates like product.bundle.liquid.
2. Custom sections and snippets - what they render and where they are used.
3. Custom Liquid logic - loops, conditionals, and tag output that a stock theme will not have.
4. Custom CSS and JS - inline styles, theme asset files, and any script tags added to theme.liquid.
5. App embeds and pasted app code - snippets an app dropped into your templates.
6. Metafield and metaobject usage - where custom data is read and displayed.
7. Settings - values in settings_data.json that reflect brand choices like colors, fonts, and layout options.

This is where AI earns its place early. Point Claude at the theme’s directory and ask it to list every file that contains custom logic, flag {% section %} references, and summarize what each snippet does. It reads the whole theme faster than a person scrolling files. Our guide on editing a Shopify theme covers how to work in theme code directly.

One caution from Shopify’s own guidance: customizations made by apps, or made manually to a theme, cannot be migrated automatically.⁵ The audit is what tells you how much manual translation is ahead.

Step 2: Map sections and settings to the new theme

With the inventory done, map each old piece to its home in the new theme. This is the plan the rest of the migration follows.

For every custom section in the old theme, decide one of three outcomes:

• Matches a built-in section in the new theme (for example, a hero or featured collection). Reuse the new theme’s section and move your settings across.
• Needs a new custom section because nothing built-in matches. You will rebuild it.
• Can be dropped because it is dead or replaced by a native feature.

Record the mapping in a simple table so nothing is lost:

Settings mapping matters as much as section mapping. Brand values in the old settings_data.json do not transfer automatically, because the new theme defines its own schema. Note the color, font, and spacing values you want to carry, then set them in the new theme.

Step 3: Use AI to translate custom Liquid into sections

This is the heart of the migration and where the repetitive load lives. Each custom template has to become a JSON template, and its code has to move into self-contained sections.

Shopify’s migration process for a single template runs like this:⁴

1. Duplicate the theme and keep it unpublished while you edit.
2. Remove {% section %} tags from the Liquid template, since section files cannot reference other sections.
3. Move the remaining code into existing sections or new ones.
4. Delete the original .liquid template, because a product.liquid and a product.json cannot both live in /templates.
5. Create the JSON template listing the section under sections and order.
6. Test the template in the theme editor.
7. Add any extra sections and set their order in the JSON file.
8. Enable app blocks by adding {% schema %} blocks of "type": "@app" and rendering with {% render block %}.
9. Repeat for every template.

Claude is well suited to steps 2 through 5. Give it the old template and the new theme’s section conventions, and ask it to split the template into self-contained sections, write the {% schema %} for each, and produce the JSON template that wires them together. It will not guess field types if you have the Shopify AI toolkit and Claude Code set up, which validates Liquid and schema against Shopify’s current rules.

A prompt that works:

Convert this vintage product.liquid into an Online Store 2.0 JSON template.
Split it into self-contained sections - no section can reference another section.
Write a {% schema %} for each section exposing the settings shown here: [list].
Output the sections and the product.json that renders them in order.

Review every output. AI removes the typing, not the judgment. Check that setting names match, that dynamic source bindings are preserved, and that no {% section %} reference survived the split.

Step 4: Port custom CSS and JS

Vintage themes often carry years of layered CSS and inline scripts. Moving them cleanly is its own task.

Practical approach:

• Scope section CSS to the section. Online Store 2.0 sections can carry their own styles, which keeps CSS with the markup it applies to rather than in one global file.
• Drop dead rules. Old themes accumulate CSS for sections that no longer exist. Ask Claude to cross-reference your stylesheet against the sections you are keeping and flag rules with no matching markup.
• Re-check JS event bindings. Scripts that hooked into old class names or IDs break when markup changes. Confirm selectors still match.

App code left behind after an app is removed is a common source of dead CSS and JS. Our guide on removing leftover app code from Shopify covers how to find and strip it during a migration.

Speed is a fair reason to migrate at all, so do not undo it by carrying junk across. See how to speed up a Shopify theme for what to check once the new theme is standing.

Step 5: Preserve metafields and templates

This is the step people fear most and it is more forgiving than expected, as long as you understand where data lives.

Metafields and metaobjects are store data, not theme data. They sit at the store level and are unaffected by which theme is published. Migrating a theme does not delete them. What lives in the theme is the display: the dynamic sources that bind a metafield to a section or block are theme-side settings.³

So the rule is:

• Metafield and metaobject definitions and values survive the theme change because they are not in the theme.
• The connections that show them - dynamic source bindings in sections and blocks - are set per theme and must be reconnected in the new one.³

During your audit, record every place the old theme reads a metafield. In the new theme, rebuild those bindings through the editor’s dynamic sources or in section Liquid. Our guide on adding metafields to Shopify products covers the display side in detail.

Alternate templates carry across as concepts but not as files. If the old theme had a page.about.liquid, you recreate page.about.json in the new theme. A theme can hold up to 1,000 JSON templates, so template count is not a constraint.²

Step 6: Test on an unpublished theme

Every step so far has happened on a duplicated, unpublished theme. Testing is why. Shopify’s migration docs open with duplicating the theme and keeping it unpublished while you work.⁴

Test with the theme still unpublished:

1. Preview every template type - home, product, collection, cart, search, blog, page, 404.
2. Check each migrated section renders and its settings behave in the editor.
3. Confirm dynamic sources show the right metafield values on real products.
4. Test app blocks on the pages that use them.
5. Walk the full purchase path from product to cart to checkout.
6. Check mobile and desktop for every key template.
7. Compare against the live theme side by side so nothing silently disappears.

A development store is a safe place to rehearse a migration before you touch the production store’s theme library at all.

Step 7: Keep a rollback plan

A migration is not done when the new theme goes live. It is done when you are confident you will not need to go back, and a rollback path is what buys that confidence.

Your rollback plan:

• Keep the old theme in the library. Do not delete the vintage theme after publishing. It stays as your one-click revert.
• Duplicate before publishing. Publish a copy of the finished new theme, not the working draft, so your draft stays clean if you need to fix and republish.
• Record settings. Note the published theme’s key settings so you can rebuild fast if something is off.
• Publish in a quiet window. Lower traffic means a smaller blast radius if you have to revert.
• Watch after launch. Check analytics and error logs in the first hours. If conversion or a key page breaks, revert to the old theme and diagnose off the critical path.

Because the old theme is untouched in your library, reverting is publishing it again. That safety net is the reason every earlier step happens on a duplicate.

Full migration checklist

Run the migration in this order:

1. Audit the vintage theme - templates, sections, snippets, custom Liquid, CSS, JS, app code, metafields, settings.
2. Map every custom element to a target in the new theme: reuse, rebuild, or drop.
3. Duplicate the new base theme and keep it unpublished.
4. Convert each Liquid template to a JSON template, splitting code into self-contained sections.
5. Write a {% schema %} for each new section and wire the JSON order.
6. Port CSS and JS, scoping styles to sections and dropping dead rules.
7. Reconnect metafield and metaobject dynamic sources in the new theme.
8. Recreate alternate templates as JSON.
9. Test every template type on the unpublished theme, including mobile and checkout.
10. Publish a duplicate of the finished theme in a low-traffic window.
11. Keep the old theme in the library as your rollback.
12. Monitor analytics and errors after launch.

Where AI fits, and where it does not

AI changes the economics of a theme migration by removing the slow, repetitive translation work. It does not remove the parts that need judgment.

AI does well:

• Reading a whole theme and cataloguing custom logic.
• Splitting monolithic Liquid templates into self-contained sections.
• Writing {% schema %} definitions and JSON templates.
• Cross-referencing CSS against surviving markup to find dead rules.
• Explaining what a piece of legacy Liquid does before you move it.

You keep:

• The section mapping decisions.
• Verifying dynamic sources and metafield bindings.
• Testing on real products and the full checkout path.
• The publish and rollback call.

For more on how AI-native tools fit modern Shopify work, see our take on AI-first Shopify development. This is also the approach behind Fudge, which generates Shopify-native sections and edits directly in themes.

Summary

A Shopify theme migration from a vintage theme to Online Store 2.0 is a rebuild, because the two architectures store templates differently. The work splits into audit, mapping, translation, metafield reconnection, testing, and rollback.

AI takes the repetitive translation off your plate - reading the old theme, splitting templates into sections, writing schemas, and finding dead code. You keep the mapping, the testing, and the decision to publish. Do all of it on a duplicated, unpublished theme, and keep the old one in the library so a revert is one click away.

FAQ