{"id":99,"date":"2025-08-10T08:39:27","date_gmt":"2025-08-10T08:39:27","guid":{"rendered":"https:\/\/magendoo.ro\/insights\/?p=99"},"modified":"2025-08-10T08:39:27","modified_gmt":"2025-08-10T08:39:27","slug":"upgrading-heavily-customized-shopify-themes-like-a-pro","status":"publish","type":"post","link":"https:\/\/magendoo.ro\/insights\/upgrading-heavily-customized-shopify-themes-like-a-pro\/","title":{"rendered":"Upgrading Heavily Customized Shopify Themes Like a Pro"},"content":{"rendered":"

Introduction:<\/strong> Upgrading a highly customized Shopify theme is not<\/strong> a simple one-click operation. Shopify explicitly warns that when you update a theme containing manual code changes, \u201cYour code changes won\u2019t be included in the updated version.\u201d<\/em> In other words, the platform will carry over theme editor settings and content (stored in JSON files like settings_data.json<\/code>), but any custom code (HTML, Liquid, CSS, JS)<\/strong> must be manually merged into the new theme version. This reality has forced Shopify agencies and developers to develop sophisticated workflows with version control, staging environments, and specialized tools to safely merge customizations. The bottom line<\/strong>: upgrading a customized Shopify theme is essentially a full development project, requiring planning, testing, and multiple safety nets to avoid downtime.<\/p>\n

Official Update Process and Its Limitations<\/h2>\n

Shopify\u2019s official documentation outlines a cautious manual process for theme updates. When an update is available, you should add the new theme as an unpublished draft<\/strong> (never overwrite the live theme), then review the release notes<\/strong>, and copy over<\/strong> your custom code changes into the new version. Settings and content changes made through the theme editor are automatically copied over \u2013 e.g. changed theme settings, sections added\/removed, or wording changes are preserved. However, any manual edits to theme files trigger a prominent warning in the Shopify Admin: \u201cYour code changes won\u2019t be included in the updated version. If you want to keep these changes, then you need to copy your code to the new version of your theme.\u201d<\/em>. Shopify\u2019s updater will only retain non-code customizations (images, text, JSON data, etc.), leaving all Liquid or CSS\/JS modifications<\/strong> for you to reconcile.<\/p>\n

In practical terms, Shopify\u2019s recommended workflow is labor-intensive. Developers must diff the old and new theme code<\/strong> to identify changes, then manually merge<\/strong> their customizations into the updated theme files. Shopify provides tools like the Shopify CLI<\/strong> to assist in development \u2013 for example, shopify theme pull<\/code> and shopify theme push<\/code> allow syncing theme code, and shopify theme dev<\/code> enables live preview on a development server. But even the CLI has its pitfalls: developers note that shopify theme push<\/code> will overwrite settings and schema files if not used carefully, often resetting configuration data if a fresh pull isn\u2019t done first. In summary, the official approach gets the job done for simple themes, but for heavily modified themes it\u2019s error-prone and requires meticulous manual effort<\/strong>. This gap between Shopify\u2019s basic tools and real-world needs has led the community to engineer far more robust deployment workflows.<\/p>\n

Multi-Environment Workflows Used by Agencies<\/h2>\n

Professional Shopify agencies rarely rely on just a single theme and manual updates. Instead, they implement multi-environment workflows<\/strong> with at least three environments: Development, Staging, and Production. Code is first integrated and tested on a Development theme, then pushed to a Staging theme for client review or QA, and only then deployed to the live Production theme. Version control (Git) is central to this process \u2013 teams keep theme code in a GitHub repository and use branches to manage updates. For example, a common setup is to have a dev<\/code> branch linked to a dev theme, a staging<\/code> branch linked to an unpublished staging theme, and the main<\/code> branch linked to the live theme. Continuous Integration pipelines then deploy changes automatically to each environment when a branch is updated.<\/p>\n

Example of a three-environment deployment pipeline for a Shopify theme. Code moves from Development \u2192 Staging \u2192 Production, with each environment being a separate theme. Integrations with GitHub and CI\/CD ensure that each branch\u2019s changes are uploaded to the corresponding Shopify theme for testing and approval.<\/em><\/p>\n

This multi-env strategy ensures that by the time code reaches the live store, it has been reviewed and tested in an environment that mirrors production. Leading agencies also emphasize keeping an \u201cinstant rollback\u201d<\/strong> plan \u2013 for instance, using a duplicate backup theme (or Shopify\u2019s built-in theme version history) so they can revert immediately if an issue is discovered after publishing. Blue-green deployment is a lifesaver during peak seasons: agencies maintain one extra \u201cblue\u201d theme that\u2019s an up-to-date clone of production. When it\u2019s time to deploy changes, they publish the updated theme as the new live version (the \u201cgreen\u201d theme). If anything goes wrong, they can revert by republishing the untouched backup theme in seconds. These practices have saved many merchants from disaster during Black Friday and other high-stakes times.<\/p>\n

Notably, some agencies choose not<\/strong> to perform tedious line-by-line merges at all for major upgrades \u2013 instead, they rebuild the site on a new base theme version. For example, Swanky Agency\u2019s case study on Medley Jewellery describes how they completely rebuilt the storefront on a new Online Store 2.0 theme template<\/strong> rather than merging code, achieving a significant performance boost (Lighthouse score for desktop improved by 38%<\/strong> and conversion rate increased 13%<\/strong> after the upgrade). Rebuilding from scratch can be faster and cleaner for heavily customized sites, because it avoids carrying over years of hacky code. The downside is it requires a full regression test of all features. Agencies will often weigh this option \u2013 if a theme has been heavily altered over time, a fresh rebuild on the latest base might be more maintainable going forward. Swanky\u2019s team, for instance, maintained all custom functionality in Medley\u2019s rebuild and treated it as an opportunity to improve site speed and UX, rather than just patching the old theme.<\/p>\n

Git Strategies: Branching and Version Control Best Practices<\/h2>\n

Modern Shopify development leverages GitHub not just for code storage but as an active part of deployment. The Shopify GitHub integration allows a theme to sync with a Git branch, so changes pushed to the repo are pulled into Shopify, and edits made in the Shopify editor are pushed back to Git. In theory this keeps code and the live theme in sync, but in practice it introduces complexity. Every change made via Shopify\u2019s editor (even a minor color tweak in the customizer) creates an automatic commit in the repo. Developers have noted that this \u201ccommit everything\u201d<\/em> behavior can clutter the commit history and cause merge conflicts, especially with the critical settings_data.json<\/code> file that stores theme settings. Best practice is to avoid connecting the live production theme directly to your main development branch<\/strong> \u2013 otherwise, if a merchant (or another dev) makes a hotfix in the live theme editor, it will auto-commit and potentially conflict with ongoing development. Many teams instead connect a separate<\/em> \u201cproduction\u201d branch to the live theme and treat it as read-only, only merging into it via Pull Requests. One developer describes abandoning a direct main\u2192live link because \u201cShopify\u2019s automatic pushes made it too annoying to manage,\u201d<\/em> opting to keep an unlinked live theme and use GitHub only for dev\/staging branches.<\/p>\n

Another advanced Git strategy for Shopify is managing multiple stores from one codebase<\/strong>. If you have separate Shopify stores (e.g. for different regions or brands) that share a common theme code, maintaining them in sync is challenging. Series Eight, a Shopify Plus agency, solved this with a branch-per-store model<\/strong>: one main development branch and separate \u201clive\u201d branches for each store (like live\/UK<\/code>, live\/EU<\/code>, live\/AUS<\/code>). Whenever changes are merged into main, GitHub Actions automatically propagate the updates to each store\u2019s branch \u2013 excluding JSON content files<\/em> to prevent overwriting each store\u2019s unique theme settings. The JSON files (which contain things like homepage section layout and store-specific content) are intentionally not auto-merged<\/strong>; instead, developers review those manually or use store-specific config for content differences. This approach allows a unified codebase across stores without risking cross-contamination of settings.<\/p>\n

Illustration of a multi-store Git workflow. A single main branch contains the core theme code. On every update to main, an automated workflow merges those changes into each store\u2019s branch (e.g. live\/UK, live\/EU, live\/AUS), while ignoring JSON template files<\/strong> to avoid clobbering store-specific content. Content or settings changes can be backfilled manually from each live branch into main as needed.<\/em><\/p>\n

Even for a single store, Git branching can separate source code from compiled theme code. Shopify\u2019s Theme CLI and GitHub integration only understand the compiled theme structure (the layout\/templates\/assets folders). If you use a build process (Webpack, Sass, TypeScript, etc.), your source files might live in a \/src<\/code> directory and get compiled to the theme structure. Shopify recommends<\/strong> keeping these separate either by using two repositories or two branches. A popular method is a monorepo with two branches: for example, a source<\/code> branch that contains your raw source code (with build scripts, package.json, etc.), and a production<\/code> branch that contains the compiled theme<\/strong> ready to deploy (no src folder, only theme files). The production branch is what connects to Shopify. With this setup, developers work in the source branch and compile, then push the build output to the production branch (sometimes using Git subtree or a CI script). Any changes made through the Shopify editor (which affect compiled theme files or settings) then have to be backfilled<\/strong> \u2013 manually copied back into the source code \u2013 to avoid getting lost on next build. It\u2019s extra work, but it keeps the commit history clean and separates development concerns. In short, never mix your unbuilt source files with the live theme code<\/strong> in the same branch; you\u2019ll end up with a mess of commits (for example, auto-generated style.css<\/code> files showing up in version control). Instead, isolate compiled code either in its own branch or repo. This discipline makes it far easier to update base themes \u2013 you can pull the latest version into a parallel \u201cupstream\u201d copy of the theme and use a three-way diff tool to merge changes.<\/p>\n

Speaking of diffs: a pro tip from the community is to use a three-way merge tool<\/strong> for updating themes. With a three-way compare, you load three versions of a file \u2013 for example, (1) your current customized theme file<\/strong>, (2) the original base theme file<\/strong> that your version was forked from, and (3) the new base theme file<\/strong> from the updated theme release. This allows you to see what the theme developer changed (diff between 2 and 3) and what you changed (diff between 2 and 1), and merge accordingly. Tools like Meld<\/strong> are popular for this process. In particular, merging Shopify\u2019s JSON files (which often have keys reordered by the theme editor) is much easier with a 3-way merge that can auto-align and highlight changes. As one expert notes, having an \u201cupstream\u201d copy of the untouched theme is crucial for this: maintain a copy of the exact base theme version your store is running (before update), so you can use it as the merge base against the new version. This way, you\u2019re not blindly comparing your theme vs. the new version; you have the context of the original to guide what changed.<\/p>\n

Continuous Integration and Deployment (CI\/CD) for Themes<\/h2>\n

To streamline the deployment process, many teams have introduced CI\/CD pipelines dedicated to Shopify themes. Tools like Buddy<\/strong> and GitLab CI<\/strong> allow automated building, testing, and deployment of theme code on every Git push. For instance, Buddy CI provides a Shopify integration that can deploy only the changed files<\/strong> to a theme (using a changeset-based deployment), which significantly speeds up the upload process. It also offers handy actions like running Lighthouse performance audits<\/strong> as part of the pipeline and Shopify Theme Check<\/strong> (linting) before deployment. This means you can catch Liquid syntax errors or performance regressions automatically, before they ever hit the live store. CI pipelines typically run tasks such as: compiling assets (if you use Sass or TypeScript), running unit tests (for any theme scripts), linting Liquid code, and then deploying to a Shopify theme. Some teams even integrate visual regression tests or use Shopify\u2019s Theme Inspector to profile rendering speed on each build.<\/p>\n

Platforms like DeployHQ<\/strong> and GitHub Actions<\/strong> also support Shopify deployments. DeployHQ, for example, lets you run build commands (Webpack, Gulp, etc.) in an isolated environment and then upload the compiled theme files to Shopify \u2013 so you don\u2019t have to commit compiled assets into Git at all. It essentially bridges the gap by performing \u201cbuild \u2192 deploy\u201d in one step. GitHub Actions can similarly be configured to run shopify theme push<\/code> on certain branches. In one public example, developers set up a GitLab CI pipeline where any push to a feature branch auto-deployed a preview theme (for QA to review), and push to main branch deployed to a staging theme, etc.. This kind of pipeline turns theme updates into a controlled release process, much like software deployments, with the ability to test every change in a real Shopify environment (via preview URLs) before it goes live.<\/p>\n

Another benefit of CI automation is preventing human error<\/strong>. Forgetting to pull latest theme code, or missing a file when copying changes, are common mistakes in manual updates. Automated diffs and deployments ensure that nothing is inadvertently left out. They also enable parallel development<\/strong>: multiple developers can work on separate feature branches which each deploy to their own preview theme. Once tested, those features can merge into the main branch for a coordinated release.<\/p>\n

Of course, even with CI\/CD, one should remain vigilant about backup and rollback. It\u2019s wise to script an automatic theme backup before any deployment (for example, Buddy can export the theme or you can use Shopify\u2019s Theme Kit to download a copy). Shopify themes do have a primitive version history (you can undo changes to a file or roll back to a previous theme version by duplicating themes), but these are not robust for full recovery. Many teams use dedicated backup apps like Rewind<\/strong> or ThemeWatch<\/strong> to snapshot their theme and store data. Rewind, for instance, can \u201cautomatically back up your Shopify store and quickly restore products, themes, and customer data\u2026undo unwanted changes with one click.\u201d<\/em> This kind of one-click restore is invaluable if a deployment goes awry \u2013 you can revert the theme to pre-deployment state in moments. In addition, maintaining a staging theme that is an exact copy of production is a good fail-safe: if a new update fails, you can literally republish the previous theme (which was kept in your library as a backup).<\/p>\n

Specialized Tools to Preserve Customizations<\/h2>\n

Given the challenges of merging theme code, a number of apps and tools have emerged to assist developers:<\/p>\n

    \n
  • Theme Updater & Backups (Out of the Sandbox)<\/strong> \u2013 This app (by a leading theme developer) automates much of the theme update process. It uses AI to analyze your current theme and the new version, and automatically applies as many custom code edits as possible to the new version<\/strong>. It highlights any conflicts for you to manually resolve. It also creates backup copies of your theme and even monitors for Shopify outages. Theme Updater has a free tier for basic updates, and a Pro plan (~$9\/month) that enables one-click \u201cAI-powered\u201d<\/em> updates preserving code customizations, plus email alerts for new theme releases. While no tool can perfectly merge every scenario, many merchants find it dramatically reduces update time. With over 250 reviews and a ~4.1 star rating on the app store, it\u2019s a proven solution for popular themes. Best practice:<\/em> even when using such tools, review the output in a staging theme to ensure no custom feature was lost in translation.<\/li>\n
  • DiffMate \u2013 Theme File Comparison<\/strong> \u2013 This free app provides a visual diff tool for Shopify themes<\/strong>. You can select any two themes in your store (say, your current theme and a new updated version) and DiffMate will show you a side-by-side comparison of every file that differs. It can filter to just changed files and even compare images. One killer feature is the ability to copy changes with one click<\/strong> from one theme to another. For example, after comparing, you can click to apply a missing code change from your old theme into the new theme directly in the app\u2019s editor. This greatly speeds up the merge process and reduces human error. Essentially, DiffMate provides an interactive checklist of \u201chere\u2019s everything that changed between versions\u201d so you don\u2019t overlook anything during an update.<\/li>\n
  • ThemeFlow \u2013 GitHub Actions for Themes<\/strong> \u2013 This is a newer app that brings Git-centric workflow automation into Shopify. It\u2019s aimed at teams using GitHub integration, providing pre-built merge and deployment flows<\/strong>. For instance, ThemeFlow can detect changes on a branch and automatically merge theme branches or deploy themes<\/strong> according to rules. It supports multi-store code sharing and scheduled or triggered merges. Think of it as a layer on top of Shopify\u2019s GitHub integration, adding features like cherry-picking commits or triggering theme publish events. ThemeFlow essentially attempts to fill the gaps to make a more complete CI\/CD pipeline within<\/em> Shopify for those who prefer an app-based solution.<\/li>\n
  • Backup and Versioning Apps<\/strong> \u2013 In addition to Rewind mentioned earlier, other apps like ThemeWatch<\/em> and ThemeSafe<\/em> focus on theme backups. These can automatically save theme file versions daily or on demand, and allow one-click restore of an entire theme (useful if an update goes horribly wrong). Some also track changes over time. While Git provides version control for code, backup apps capture everything in the Shopify store (including settings and content). Using a combination of both is wise: Git for your code history, and a backup app for the store data and emergency recovery.<\/li>\n<\/ul>\n

    In summary, a robust \u201cupgrade toolbox\u201d might include a diff tool (DiffMate or even manual Git diffs), an updater utility (Theme Updater app or the Shopify Theme Inspector for Chrome), and a backup solution (Rewind or similar). These tools don\u2019t eliminate the need for developer oversight<\/strong> \u2013 but they can eliminate busy-work and catch mistakes. Automated diffing, in particular, addresses the biggest pain point: knowing exactly what the theme developer changed in the new version and what you customized in the old version. Armed with that knowledge, you can merge confidently.<\/p>\n

    Key Best Practices for Smooth Theme Updates<\/h2>\n

    Upgrading a customized theme will never be fully \u201chands-off,\u201d but following these best practices will ensure a smooth, professional process:<\/p>\n

      \n
    • Plan Updates Like Software Releases:<\/strong> Treat a theme upgrade as a mini software project. Scope out the changes, schedule downtime or low-traffic deployment windows, and allocate sufficient developer hours (major version upgrades can take 20\u201340 hours for heavily customized stores \u2013 plan accordingly).<\/li>\n
    • Use Multiple Environments:<\/strong> Never edit or update the live theme directly. Always use a development theme for integration and a staging theme for final testing. Only publish the new version after it\u2019s been vetted on staging by your team and the store owner. This prevents nasty surprises on the live site.<\/li>\n
    • Leverage Git and CI\/CD:<\/strong> Maintain your theme code in Git, and use branches to control deployments. Implement CI scripts or apps to automate builds and deployments to your dev and staging themes on every commit. This catches issues early and makes the deployment process repeatable. Protect the main production branch \u2013 use Pull Requests and code reviews for any changes that will go live.<\/li>\n
    • Document and Comment Custom Code:<\/strong> When you do customize theme code, leave comments (<!-- custom code for XYZ --><\/code>) and keep a change log. This is invaluable during an update merge \u2013 you\u2019ll know what code blocks were custom vs. stock. It also helps to have an \u201cupstream base\u201d<\/strong> copy of the theme (unmodified) for reference.<\/li>\n
    • Use Diff Tools for Updates:<\/strong> When a new theme version releases, perform a thorough diff between your current theme and the new version. Identify all code differences. Tools like DiffMate or Meld can speed this up by highlighting changes and even merging for you. Don\u2019t rely on memory or manual checking \u2013 it\u2019s too easy to miss a small snippet.<\/li>\n
    • Don\u2019t Overlook Settings and Content:<\/strong> Remember that new theme versions might introduce new settings or sections. Manually port over any JSON from templates\/*.json<\/code> and config\/settings_data.json<\/code> carefully if not done automatically. Conversely, be mindful that your existing settings_data.json<\/code> will overwrite the default settings in the new theme \u2013 some of those defaults might be needed for new features. Always review the theme settings in the customizer after an update.<\/li>\n
    • Backup Before and After:<\/strong> Always create a backup (duplicate theme) before you begin an update. And after you finish merging and testing the new version (prior to publishing it), download a copy or use a backup app to snapshot it. This way, you can roll back or even start over if needed. Shopify allows duplicating themes in the admin with one click \u2013 use this liberally to create \u201csave points.\u201d<\/li>\n
    • Test Thoroughly:<\/strong> Test the updated theme in staging across all critical flows: add-to-cart, checkout, product filtering, etc., on multiple devices and browsers. Pay special attention to any custom apps or scripts \u2013 ensure they still work or have been re-integrated. Also test site speed (compare Lighthouse scores) to catch any performance regressions early.<\/li>\n
    • Have a Rollback Plan:<\/strong> Despite best efforts, things can go wrong on deployment. Make sure you have an immediate rollback plan: for example, keep the previous theme version unpublished in the theme library. If a serious issue appears on the live site, you can quickly republish the old theme (or use an app\u2019s one-click restore) to minimize disruption. In high stakes periods (holidays), consider delaying theme updates entirely unless they\u2019re absolutely necessary.<\/li>\n<\/ul>\n

      Conclusion<\/h2>\n

      Upgrading a customized Shopify theme is undeniably challenging \u2013 but with the right approach, it\u2019s manageable and can even be routine. The key is recognizing that automation can assist but not fully replace developer insight<\/strong>. Shopify\u2019s platform provides a solid foundation (Theme CLI, GitHub integration, theme checkpoints), and on top of that the ecosystem now offers powerful tools to fill the gaps (CI\/CD pipelines, update apps, diff utilities). The most successful teams combine these tools with disciplined workflows: multi-environment testing, strict version control, detailed documentation of customizations, and backup\/rollback strategies.<\/p>\n

      At the end of the day, an updated theme is only a success if the store\u2019s functionality and conversions are preserved (or improved)<\/strong>. This means zero downtime, no missing features, and hopefully some new benefits from the latest theme version. Reaching that point requires an investment in process. As we\u2019ve seen, leading Shopify agencies treat theme upgrades not as a trivial task but as a full development cycle<\/strong> \u2013 complete with project timelines, QA, and often performance improvements as a bonus outcome. By planning meticulously and using the best practices outlined above, Shopify developers and CTOs can upgrade customized themes \u201clike a pro,\u201d keeping their storefronts modern and secure without sacrificing the custom touches that drive their business. In ecommerce, you can\u2019t afford surprise breakages or downtime, so approach your next theme update with the rigor it deserves. With the right workflow, you\u2019ll reap the benefits of Shopify\u2019s latest features and optimizations, while keeping your hard-earned customizations intact<\/strong>.<\/p>\n","protected":false},"excerpt":{"rendered":"

      Introduction: Upgrading a highly customized Shopify theme is not a simple one-click operation. Shopify explicitly warns that when you update a theme containing manual code changes, \u201cYour code changes won\u2019t be included in the updated version.\u201d In other words, the platform will carry over theme editor settings and content (stored in JSON files like settings_data.json), […]<\/p>\n","protected":false},"author":1,"featured_media":100,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"site-container-style":"default","site-container-layout":"default","site-sidebar-layout":"default","disable-article-header":"default","disable-site-header":"default","disable-site-footer":"default","disable-content-area-spacing":"default","footnotes":""},"categories":[14],"tags":[],"class_list":["post-99","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-shopify"],"_links":{"self":[{"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/posts\/99","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/comments?post=99"}],"version-history":[{"count":1,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/posts\/99\/revisions"}],"predecessor-version":[{"id":101,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/posts\/99\/revisions\/101"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/media\/100"}],"wp:attachment":[{"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/media?parent=99"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/categories?post=99"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/magendoo.ro\/insights\/wp-json\/wp\/v2\/tags?post=99"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}