Modernizing a legacy Shopify theme from Online Store 1.0 to Online Store 2.0 architecture

What was happening

The older theme had grown around legacy template conventions where page composition and merchant customization were more limited. Important content and layout decisions were tied closely to Liquid templates, hardcoded settings, or one-off custom sections. As the store added more landing pages, product merchandising, apps, and campaign requirements, the legacy structure created unnecessary developer dependency and made repeated layouts harder to reuse cleanly.

Why the obvious solution was not enough

The migration had to modernize the architecture without changing the store's underlying commerce behavior or losing business-specific customizations. Existing product data, metafields, navigation, tracking, app integrations, responsive styling, and custom storefront behavior all needed to be mapped into the new structure. A successful migration also had to avoid recreating the old theme inside a new folder structure with the same technical debt.

How the solution works

1. Audit the legacy templates and identify which responsibilities belong to layout, template, section, snippet, asset, setting, metafield, or application layers.
2. Convert page composition to JSON templates where appropriate so sections can be arranged and configured without editing Liquid template files for every layout change.
3. Move reusable content blocks into configurable sections and blocks with clear schema settings rather than embedding content directly in templates.
4. Use metafields for structured product or page data that belongs to the merchant's content model, keeping presentation logic separate from stored business data.
5. Refactor repeated Liquid into snippets or reusable section patterns so the same behavior is not maintained independently across multiple templates.
6. Replace legacy app insertion patterns with supported theme app extensions or app blocks where the installed application provides them.
7. Review global JavaScript and CSS during migration, separating feature-specific behavior from code that genuinely belongs on every storefront page.
8. Rebuild each template around the modern architecture, then compare storefront behavior and editor controls against the legacy theme before release.
9. Document the new content model so future editors and developers know when to use a section setting, block, metafield, snippet, app block, or custom code.

const storefrontArchitecture = {
  jsonTemplate: 'page composition and section order',
  section: 'merchant-configurable feature or content region',
  block: 'repeatable content inside a section',
  snippet: 'reusable rendering logic',
  metafield: 'structured business or product data',
  appBlock: 'supported app-owned storefront UI',
  asset: 'scoped CSS and JavaScript behavior',
};

What should be verified before shipping

• Compare every migrated template with its legacy equivalent for required content, merchandising, forms, product behavior, and customer flows.
• Confirm section and block settings are understandable to a store administrator and do not expose unnecessary implementation detail.
• Verify structured data is stored in the correct Shopify field or metafield instead of being duplicated inside presentation settings.
• Test app blocks, app embeds, analytics, pixels, and third-party integrations after migration because legacy insertion points may no longer be appropriate.
• Check that reusable sections work on more than the first template they were built for and do not depend on hidden page-specific assumptions.
• Run mobile, accessibility, performance, and visual regression checks before replacing the legacy production theme.
• Document rollback and keep the previous live theme available until the Online Store 2.0 release is verified.

What changed

The storefront moved from a legacy theme structure into a more modular Shopify architecture that reduced hardcoded page composition, improved merchant control, and created cleaner extension points for future development. New landing pages, merchandising sections, app integrations, and structured product content could be added without continuing to expand the same legacy template debt.

Reusable lesson

Modernization is successful when the architecture changes how future work is done. Moving to Online Store 2.0 should reduce coupling between content, layout, integrations, and custom code rather than simply reproducing the old theme inside newer Shopify files.

How I would evaluate this today

The migration strategy should follow the capabilities of the current theme and installed apps rather than assuming every legacy customization needs a custom replacement. Native sections, dynamic sources, metafields, and supported app extensions should be preferred when they meet the requirement cleanly.