horizon-theme-safe-customization-en

How to safely customize Shopify's new theme, "Horizon"

The Horizon Theme Safe Customization Guide , published by Shopify's official Growth Services last November, introduces a systematic approach to customization while maintaining upgradability.

Here, I would like to summarize the key points of the guide and explain, from the perspective of someone who actually manages and operates store themes, how far you should go and what you should prioritize, while also sharing my personal views.

The underlying idea: "Don't touch vendor files"

The official guide consistently emphasizes the principle of not directly editing the original theme files (vendor files) . By adhering to this policy, you can reflect the latest theme features without affecting your custom files.

Six customization phases

The official guide recommends dividing the customization into six phases.

Phase 0: Preparation and benchmarking

Before you begin customization, make the following preparations:

  • Connect your theme to GitHub and create upstream/horizon (for tracking the original) and main (for customization) branches.
  • Theme Check Settings
  • Creating a changelog ( docs/changes.md )

The method proposed here assumes version control via GitHub, but I think that most general stores do not use this type of management. However, once you switch to this management method, you will be impressed by its convenience. It offers many benefits, such as the ability to roll back to a previous state when a problem occurs, or when and who touched it. This may be a good opportunity to switch to GitHub management.

The official guide simply says to "create an upstream branch," but if you create this branch incorrectly, subsequent upgrade operations will fail, so after trying several methods, I settled on the following approach.

Recommended branch structure

There are several ways to create a branch, but if you use the wrong method, problems will occur when merging. We decided that it would be best to create upstream/horizon only once as orphan, and then stack commits on this branch from then on.

How to do it pattern First time Second time onwards Merge issues
Create a new orphan branch every time orphan orphan Since there is no common ancestor , all files are treated as new additions, resulting in huge differences every time.
Cut a branch from main and replace the contents Branch from main Branch from main There is a risk that Git will interpret this as "you intentionally deleted custom.* " and your custom files will be lost.
Orphans are only used the first time, and are then stacked on the same branch. orphan Overwrite commit to the same branch Only changes are merged (minimal diff)

There are three points.

  • There is only one branch upstream/horizon . A new branch is not created for each version (as the official guide mentioned above states, Although it says to create a branch for each version, such as upstream/ horizon-vX.YZ , we will not do this and will always update the contents of one branch.
  • Versions are distinguished by tags ( upstream/v3.2.1 , upstream/v3.3.1 )
  • Because the history is connected, Git can correctly calculate the difference between v3.2.1 and v3.3.1, and merge only the changes into main.

Phase 1: Globally loading custom CSS/JS

Create a file called snippets/custom.globals.liquid to centralize your custom CSS and JS loading. The only change to layout/theme.liquid is this one include line.

One line to add to layout/theme.liquid :

 {%- render 'custom.globals' -%}

Contents of snippets/custom.globals.liquid: 

 <link
 href = " {{ 'custom.css' | asset_url }} "
 rel = "stylesheet"
 >
 <script
 src = " {{ 'custom.js' | asset_url }} "
 type = "module"
 fetchpriority = "low" 
></script>

This snippet loads custom.css and custom.js from the assets. Even if you add more custom files in the future, you can simply add them to this snippet.

Changes to the layout file are limited to "just one place," and custom.css and custom.js are loaded in the snippets file below, so you can centrally manage the target files without complication.

Phase 2: Theming and Metafields

Avoid hard-coding and manage data dynamically using theme settings ( settings_schema.json ) and meta fields. Colors, intervals, and function ON/OFF can be changed from the theme editor.

When working with Horizon, it is strongly recommended to avoid modifying the code as much as possible, customize it through section and block settings, and reference metafield values ​​for dynamic values. However, there may be cases where the relevant setting item does not exist, so it may depend on the time and situation.

Phase 3: Creating Custom Sections

If you want to create your own custom section, instead of editing the vendor's section file, create a new section with custom. . prefix.

  • sections/custom.main-product.liquid … Create a custom version
  • templates/product.json … Change to reference the custom version

Leave the vendor version as is so you can revert back to it at any time.

This method is ideal, but if you copy the entire section of the vendor version to create a custom version , you will end up having to reflect the changes in the vendor version in your custom version when you update. It's hard to say how much work this will involve, as it depends on the content of the theme update, but it seems safe to say that it's best not to create too many custom sections.

Phase 4: How to add measurement tags and external tools

There are many cases where you may want to add code from external services to your theme, such as GA4, Google Ads measurement tags, chat tools, etc. Traditionally, the code was pasted directly into theme.liquid , but this method required you to re-paste the code every time you updated the theme, and could lead to conflicts.

Shopify now offers several mechanisms that allow you to incorporate external services without touching your theme files . Because they don't touch your theme, your settings won't be lost even if you update, and you can continue to use them as they are even if you switch themes.

How to choose an installation method (try them in order from top to bottom):

  1. If there is an official app available, use it - it's the safest and easiest way, as it doesn't require you to write any code.
  2. If not, register the code with "Custom Pixel" - This can be set from "Customer Events" in the Shopify admin panel, and it runs in a safe place separate from the theme, so it does not affect the theme.
  3. If that doesn't work, the last resort is to write it in custom.globals - Since you will be using theme files, you need to be careful when updating

Take Google Tags for example:

Google measurement tags are the most common scripts used in stores, and the current implementation methods can be summarized as follows:

  • Google & YouTube App - GA4 and Google Ads tags are supported by this official app (not GTM)
  • Custom Pixel - A way to run a GTM container in a sandbox (not officially supported by Google, but widely used)
  • Direct embedding in theme.liquid - the old way (now deprecated)

In addition, Google's own help page clearly states that GTM cannot be configured via the Google & YouTube app, and advises users to migrate any Google tags running within a GTM container to the app.

For GA4 or Google Ads tags, it's safest to first use the Google & YouTube app. If you want to use GTM, a custom pixel is a realistic option, but you should be aware that it's not officially supported by Google. In any case, since embedding GTM tags directly in theme.liquid is not recommended, it seems best to avoid the traditional method of writing GTM tags directly in theme files with Horizon.

Phase 5: Styling Strategy

  • Aggregate custom styles in assets/custom.css
  • Do not edit vendor CSS directly
  • Leveraging CSS variables to limit scope

Phase 6: Check for accessibility and performance

  • Aim for a Lighthouse score of 90 or above
  • Keyboard and screen reader testing

The Lighthouse score is directly related to SEO. It is a good idea to check the score every time you make a customization and be able to immediately revert it if there is any problem.

Summary: What should you do in the end?

I'll summarize what I've covered so far as simply as possible. I believe there are only three basic rules you should follow to safely customize Horizon and continue to benefit from updates.

  1. Theme files are all managed on GitHub, so all changes are recorded, including who made what changes and when. If any problems arise, you can always revert to the previous state, so you can rest assured.
  2. Don't directly edit the files that come with the theme. <br>If you want to change the design or functionality, instead of rewriting the original files, create and add your own file (such as custom.css ). This way, your customizations won't be broken even if the theme is updated.
  3. Load all the CSS and JS you want to add in one file <br>The loading of files you've added will be consolidated into one file called custom.globals.liquid . Since everything is managed in one place, you won't lose track of what you've added.

If you follow these three steps, you won't have to worry about theme updates, and you can save on more advanced customizations like creating custom sections or extending theme settings until you really need them.

"Themes are not consumables, but assets that need to be nurtured." Putting a little bit of structure in place at the beginning will lead to long-term stability in store operations.

Back to blog