Shopify Store Migration: Our Section Porting Workflow

Merchants keep selling while their homepage disappears from the migration duplicate — usually because a section file exists in sections/ but never landed in index.json order. This porting workflow is what K2 Devworks runs on legacy-to-OS-2.0 migrations when production HTML is truth and Figma is stale.

Store migrations are not copy-paste theme ZIP jobs. They are archaeology: legacy snippets referencing undefined variables, homepage hardcoded in theme.liquid, merchant content trapped in settings_data.json from a theme that predates JSON templates, and apps that injected ScriptTags everywhere. Our section porting workflow is the bridge — how we inventory what exists, decide port versus rebuild, convert HTML and Liquid into OS 2.0 sections, wire JSON templates without losing narrative order, and QA before switchover. Nishad led six major migrations in 2024–2025; Dhruv ran conversion sprints on each. This is the playbook we wish the first migration proposal had included, before someone published an empty index.json to production on launch night.

Phase 1: Legacy theme audit and section inventory

Before writing new files, export the live theme and catalog every surface: templates/*.liquid, sections/ if any, snippets/, assets with highest CSS weight, and settings_data.json for merchant customizations. We build a spreadsheet: Legacy surface, Future section filename, Port or rebuild, Block or flat, Content owner, Risk. Homepage slideshow in theme.liquid becomes sections/hero-slideshow.liquid on index.json. Collection template with hardcoded sidebar becomes collection.json sections. Missing inventory guarantees duplicate work — two developers building different hero implementations. Section workflow intake checklist applies here with migration-specific columns.

Phase 2: Choose migration base theme

We pick the target base: Dawn fork for performance-focused DTC, premium OS 2.0 theme if client already licenses one, or clean custom repo if enterprise constraints exist. Porting into a chaotic existing repo without OS 2.0 discipline costs more than starting Dawn plus porting custom sections. Exception: client has forty custom sections already on JSON templates — incremental migration wins. Document base choice in SOW so stakeholders do not expect Prestige features on Dawn budget.

Phase 3: Extract HTML and merchant content

For each legacy module, capture rendered HTML from production (view source or theme inspector) and screenshot theme editor settings where they exist. Legacy settings_data.json keys map to future schema ids — we align intentionally: old slideshow_speed becomes autoplay_speed with migration note. When ids cannot align, export copy to CSV for merchant re-entry. Figma may be stale; production is truth for migrations. Figma HTML to section workflow accelerates when design files match production; when they do not, production HTML goes into converter first.

# Migration mapping excerpt (internal spreadsheet columns)
legacy_file          | new_section           | schema_notes
theme.liquid hero    | hero-slideshow.liquid | blocks per slide
snippets/old-card    | card-product.liquid   | merge into shared snippet
page.contact.liquid  | contact-form section  | new on page.json

Phase 4: Port versus rebuild decision tree

Port when Liquid logic is sound, dependencies are few, and CSS can scope under section.id. Rebuild when legacy code uses include chains, global CSS leaks, or non-OS-2.0 patterns like settings in templates without schema. Rebuild feels slower day one but faster by week three. Converter-first rebuild for marketing modules; manual port for main-product-adjacent logic requiring variant integration. HTML to Shopify Liquid guide and converter evaluation support rebuild path.

• Port — FAQ accordion with clean markup, product metafield panels, trusted snippet loops
• Rebuild — homepage in theme.liquid, slider with jQuery dependencies, non-schema settings
• Hybrid — port Liquid logic into new section file with rewritten schema and scoped CSS
• Drop — deprecated features, unused sections, app replaces custom code entirely

Phase 5: Conversion sprint mechanics

We run conversion sprints: one developer owns two to three sections per day through converter, schema polish, presets with migrated defaults, Theme Check, and theme editor smoke test. Parallel track wires JSON templates — index.json, product.json, collection.json — as sections merge. Section files land useless until registered in template order arrays; migration PM tracks both columns. Schema Generator speeds id renames when preserving merchant-facing labels. Block sections get shopify_attributes on every row — legacy HTML never had them; migration is the time to add, not launch week.

{%- comment -%} Ported hero — scoped CSS replaces legacy global rules {%- endcomment -%}

  {% for block in section.blocks %}
    

      {% if block.settings.image != blank %}
        {{ block.settings.image | image_url: width: 1600 | image_tag: loading: 'lazy' }}
      {% endif %}
      
{{ block.settings.heading }}
    
  {% endfor %}

Phase 6: JSON template wiring and order parity

Merchants remember homepage narrative order even if they cannot name JSON. We replicate legacy order in index.json order array unless marketing signed a new wireframe. Side-by-side staging URL comparisons: old theme versus migration duplicate, section by section. Missing order entry is the number-one "migration broke my store" ticket — section exists in code, absent on storefront. We validate with theme editor screenshot checklist: every legacy module has a visible counterpart or documented deprecation.

Phase 7: Apps, ScriptTags, and cleanup

Migrations expose app cruft: legacy review widgets hardcoded while app block should replace, duplicate analytics snippets in theme.liquid and checkout. Audit apps in admin, map to theme app extensions or OS 2.0 app blocks, remove ScriptTag injections superseded by theme code. Cart and drawer apps get special testing — cart drawer guide patterns differ on migration base. Defer app reinstall until theme stable; changing theme and apps simultaneously obscures root cause of bugs.

Phase 8: Content freeze and cutover

We negotiate content freeze windows: no major homepage edits on legacy theme during final week. Cutover checklist: duplicate migration theme one last time, export settings backup, publish migration theme during low-traffic window, smoke test checkout, verify markets if applicable, monitor 404s and Search Console. Rollback plan stays one click — republish previous theme — until client signs acceptance. Merchants re-enter only what migration CSV documents as unmapped.

QA gates specific to migrations

Beyond standard section QA, migrations need parity QA: legacy URL handles, collection counts, metafield display, gift card products, B2B customer tags if Plus, and international pricing. We test top twenty revenue SKUs on product template. Visual diff tools help; human eyes catch brand spacing regressions automated tools miss. HTML to Liquid converter guide validation rules catch schema issues before they block editor during merchant retraining.

Migration failures we have seen

• Published theme with empty index.json order — blank homepage.
• Renamed schema ids — merchant slideshow content wiped.
• Ported global CSS broke collection grid site-wide.
• Removed legacy snippet still called by forgotten page template.
• App block not enabled in main-product — reviews vanished post-migration.
• No rollback theme kept published — hours downtime during hotfix.

Merchant communication during migration

Migrations stress merchants. Weekly Loom updates showing staging progress, plain-language explanation of OS 2.0 benefits (editable sections), and honest list of content they must re-enter builds trust. Training scheduled for after publish, not before — they forget. Link section tutorial and internal Notion mapping Figma names to section names. Dhruv narrates; operations teams ask real questions that improve schema labels before handoff.

Estimating migration section work

We estimate per module from inventory spreadsheet, not gut feel. Flat marketing section: 3–5 hours. Block section with metafields: 8–16 hours. Full homepage ten modules: 1.5–2 weeks dev plus QA buffer. Add 20% for legacy surprises — theme.liquid conditionals nobody documented. Fixed-price migrations without inventory audit are how agencies lose margin. Sell discovery sprint first; port workflow second.

Metafield and metaobject migration

Legacy themes often hardcoded content that modern stacks store in metafields and metaobjects. Section porting includes mapping old theme settings to new metafield definitions, exporting CSV from admin, importing to new store if domain changes, and updating Liquid to read product.metafields.custom.ingredients instead of section.settings on every PDP. We define metafields before section porting so schema uses dynamic sources consistently. Metaobject-driven sections — size charts, store locator rows — need admin setup before Liquid loops work in staging.

URL redirects and SEO preservation

Template migrations change URL patterns rarely on Shopify, but blog handles, page renames, and collection merges need redirect lists. Section porting coincides with IA changes — homepage sections reorder, old landing pages deprecate. Export redirect CSV before cutover. New FAQ sections help SEO but do not replace redirects for removed URLs. Coordinate with SEO agency week before publish; developers provide old-to-new URL map from template audit.

Parallel running and stakeholder demos

We demo migration themes on duplicate store URLs weekly — side-by-side legacy versus OS 2.0 section parity. Stakeholders approve module-by-module in spreadsheet, not in vague looks-good emails. Parallel running reduces launch surprise when operations discovers a port dropped B2B registration band. Record which sections are intentionally deprecated versus pending phase two so sales teams do not promise features still in legacy only.

Third-party theme versus custom porting

Migrating off premium third-party themes — Prestige, Impulse, custom agency builds — requires licensing check on ported sections. We do not copy proprietary theme code into client repos without rights. When porting is licensed or client owns code, still rebuild with scoped CSS and OS 2.0 schema rather than paste legacy files. Premium themes often have better snippet architecture to study than copy — learn patterns, rewrite clean.

Post-migration support window

We contract thirty-day post-migration support for editor questions and hotfixes — not indefinite free tweaks. Support tickets during window feed FAQ updates in handoff doc. Common post-migration: merchants duplicate sections expecting global update (they are independent instances), delete blocks thinking content is saved (it is gone), upload wrong image aspect ratio in new hero. Training Loom recorded at publish plus support window catches ninety percent; remaining ten percent becomes schema label improvements.

Migration tooling stack

Tools dock during migration sprints: Shopify CLI for theme pull/push, HTML to Liquid converter for rebuild modules, spreadsheet for inventory, Theme Check in CI, Beyond Compare for settings_data.json diff, Loom for stakeholder updates. We do not migrate via ZIP email attachments — Git history is audit trail when merchant asks what changed between legacy and new homepage six months later.

Content mapping spreadsheet columns

Our migration spreadsheet columns: Legacy source, New section type, Port/rebuild, Setting id map, Metafield map, Merchant re-entry required (Y/N), QA status, Stakeholder sign-off date. PM owns sign-off column; dev owns QA status. Incomplete spreadsheet blocks publish — not optional paperwork. When client asks why launch slipped, spreadsheet shows which modules lacked approval versus which were dev incomplete.

Risk register for migration projects

Top risks we document upfront: undocumented legacy apps, merchant editing live theme during migration, scope creep new homepage sections mid-migration, SEO redirect gaps, B2B customer pricing edge cases, app blocks incompatible with new main-product. Each risk gets owner and mitigation — e.g. content freeze date, app audit week one. Risk register shared with client steers conversation away from fantasy launch dates.

Velocity without skipping phases

Clients pressure faster migration. Phases compress — inventory and porting same week — but phases do not skip. Skipping inventory causes duplicate sections; skipping JSON wiring causes blank homepage; skipping QA causes launch rollback. QA checklist runs on every ported section even when timeline is tight. Parallel developers on different sections still merge through single inventory spreadsheet to avoid filename collisions and duplicate hero implementations.

Legacy snippet and asset cleanup during port

Migration is the right time to delete unused snippets and orphaned assets — legacy.js from 2019 slider, six versions of icon sprites. Grep snippet names before delete; remove from assets/ only after zero references. Cleaner theme port is easier to maintain than carrying dead files for sentiment. We tag deleted files in migration changelog so rollback is possible if obscure page template still referenced old snippet.

Celebrating migration wins with merchants

Merchants fear migration means starting over. Demo theme editor wins explicitly: drag FAQ row, swap hero image, add block without ticket. Contrast with legacy theme where they emailed agency for text changes. Emotional buy-in reduces post-launch nitpicking on pixel differences. Technical port quality and merchant empowerment narrative ship together — handoff checklist covers training; migration workflow covers why OS 2.0 was worth the disruption.

Migration success is measured in merchant content preserved and orders uninterrupted — not in how many section files landed in Git.

Start your migration inventory

Export live theme today. List every homepage module and its legacy source file. Mark port versus rebuild. Pick target base. Run one module through full pipeline — converter, schema, index.json registration, QA — before committing to a launch date. Section porting workflow is sequential for a reason; skipping inventory creates the migrations that become rescue projects six months later. The first module you port teaches you how long the rest will really take.

Partner with operations early: they know which legacy sections merchants actually use versus which everyone ignores. Porting unused legacy sliders wastes budget; deprecating them with client sign-off frees timeline for sections that drive revenue. Migration is opportunity to simplify, not photocopy every 2018 homepage band.

Assign a single migration lead who owns the inventory spreadsheet and publish/no-publish decision — not a committee. Committees migrate forever. The lead has authority to cut scope with client approval when timeline threatens launch. Clear ownership prevented a three-month migration becoming six on a furniture client where every stakeholder added "just one more" legacy band.

Celebrate migration launch internally — team shipped under pressure. Morale matters for the support window that follows. Then sleep. Migrations are marathons; the workflow exists so the next one starts from experience, not panic. Document lessons learned within forty-eight hours while memory is fresh — future you will thank present you. The migration spreadsheet becomes the template for the next client in the same vertical. Reuse column structure and risk register format — do not reinvent migration ops per project. Standardization is how agencies profit on migration work instead of bleeding margin every single quarter. That discipline compounds over time.