---
title: "Shopify Theme Customization: A Safe Workflow"
description: "Customize a Shopify theme safely by working in order: try settings, sections and app blocks first, make every change on a duplicate or development theme, keep custom code in its own files under version control, run Theme Check, work through a short QA checklist, then publish with the old theme kept as your rollback. Stop customizing when the theme itself is the problem."
author: "Ecompanda"
date: 2026-03-07
updated: 2026-10-17
category: "Shopify development"
readingTime: "11 min read"
canonical: https://www.ecompanda.co/blog/best-practices-for-shopify-theme-customization
source: https://www.ecompanda.co
---

# Shopify Theme Customization: A Safe Workflow

_By Ecompanda. Published March 7, 2026, updated October 17, 2026._

Customize a Shopify theme safely by working in order: try settings, sections and app blocks first, make every change on a duplicate or development theme, keep custom code in its own files under version control, run Theme Check, work through a short QA checklist, then publish with the old theme kept as your rollback. Stop customizing when the theme itself is the problem.

The safe way to customize a Shopify theme is to work in a fixed order. Try settings, sections and app blocks first. If you need code, write it on a duplicate or development theme, keep it in its own files under version control, run Theme Check, work through a short QA checklist, and only then publish, keeping the old theme as your way back.

This guide is for store owners who want to know what their developer should be doing, and for developers who want a checklist. It was rewritten and checked against Shopify's documentation on 17 October 2026. It covers process only. For Dawn specifically, read our [Dawn customization guide](https://www.ecompanda.co/blog/shopify-dawn-theme-customization-the-complete-guide).

## The workflow: settings first, code last

Most theme accidents start with one shortcut: editing the live theme directly. This workflow removes it.

![A flow chart. A change is requested. Can a setting, section or app block do it? Yes: use the theme editor on a duplicate draft theme. No: write code on a copy, in a Git branch, in your own files. Both paths lead to Check (Theme Check and previews), then the QA checklist, then Publish, where the old theme moves to Draft themes. Finally either write it in the change log, or republish the old theme and fix on the copy.](https://cdn.sanity.io/images/9g0lkkr3/production/398d517a3ad9c6387141315a6617f13a7a11adb4-1200x1747.png?w=1400&auto=format)
_Our customization workflow, from request to rollback, Ecompanda, 17 October 2026_

The first question decides how much risk you take on. A setting or block in the theme editor is data: you can move, hide or remove it without touching code. Shopify's Help Center says to edit theme code only if an app or the theme editor can't do the job, and warns that code changes incompatible with a theme update are removed in the updated copy.

Before you open the code editor, ask in order:

1. Is there a theme setting for it (colors, fonts, header and footer options)?
2. Can you add or rearrange a section or block? Our [sections and blocks guide](https://www.ecompanda.co/blog/shopify-sections-and-blocks-explained-the-complete-guide) explains what your theme allows.
3. Does an app already do this, and does it offer an app block?
4. Only then: write code.

Settings also make updates easier. The Help Center says that when you update a Theme Store theme, edits made in the theme editor are copied across: settings, section and block layout, new templates, app embeds and wording. Code edits are included only if they don't conflict with the update.

## Work on a copy, never on the live theme

### Duplicate the theme

In the admin, go to Online Store, open the theme's actions menu and choose Duplicate. The copy is named "Copy of" plus the theme name and sits in your draft themes. Shopify's Help Center gives the reason in one line:

> "Duplicate your theme to create a backup copy."

Source: [Editing theme code](https://help.shopify.com/en/manual/online-store/themes/theme-structure/extend/edit-theme-code), Shopify Help Center.

Three details matter:

- You can have up to 20 themes in the admin, and only one is published. At 20 you must delete one before you can duplicate, and deleting is permanent.
- A duplicate copies code and settings. A theme download does not include products, collections, menus, pages, blog posts or files.
- Rename your drafts. "Copy of Dawn" is not enough once you have four of them.

### Use a development theme for code work

For code, work on your own machine with Shopify CLI. The command `shopify theme dev` uploads your local theme as a development theme: a temporary, hidden theme on your store. Per Shopify's documentation, it uses the store's real data, hot reloads CSS and section changes, doesn't count toward your theme limit, and is deleted after seven days of inactivity or when you run `shopify auth logout`. It also gives you a theme editor link and a shareable preview link.

The `theme dev` reference notes that you can't preview checkout customizations at its local address, and Shopify's tutorial says the local preview works in Google Chrome. Test the checkout another way (see the QA section).

If you work on a client's store, ask for collaborator access with the Themes permission, as Shopify's tutorial for customizing a merchant theme recommends.

## Version control: GitHub integration and Shopify CLI

Version control answers two questions that otherwise cost hours: what changed, and who changed it. Shopify says you can use the CLI together with the GitHub integration.

![The top of Shopify's documentation page for the GitHub integration for themes, listing its features and a note that files are updated in GitHub whenever a connected theme changes.](https://cdn.sanity.io/images/9g0lkkr3/production/25d4b635d4350c3d2b37474b5baed818faf0ac19-780x940.jpg?w=1400&auto=format)
_Shopify's documentation for the GitHub integration for themes, shopify.dev, 17 October 2026_

### What the GitHub integration does

The integration updates your theme whenever the connected branch changes, and commits changes made in the admin back to the branch. Worth knowing before you connect:

- **Admin edits become commits.** Theme editor and code editor changes are committed by Shopify. Edits saved within about 10 seconds are batched, and the commit names the person who saved last. This can't be turned off.
- **The branch must look like a theme.** Only branches matching the default folder structure connect: `assets`, `blocks`, `config`, `layout`, `locales`, `sections`, `snippets`, `templates`. Other folders are ignored.
- **A disconnected branch can't be reconnected.** Reconnecting adds a new theme.
- **Conflicts are real.** The code editor has no conflict alerts and overwrites the GitHub version of a file. If a theme falls behind its branch, use Actions, then Reset to last commit, on the theme card.

To connect, install the Shopify GitHub app, then use Add theme, then Connect from GitHub, and pick the repository and branch. Shopify's page suggests a test: change a setting, save, and look for a commit from the Shopify bot.

### A branch plan that fits

Shopify's version control guidance suggests connecting your main branch and publishing that theme, so the live theme matches main. For a sale or campaign, use another branch and publish its theme temporarily, then republish main's theme afterwards. If you use a build step, connect a separate deploy branch that holds only compiled theme files.

### A CLI session, start to finish

This is our sequence for a code change on an existing store.

```bash
# 1. Download a copy of a theme (you choose from the list)
shopify theme pull --store my-store --path ./my-store-theme

# 2. Work with live preview on a hidden development theme
cd my-store-theme
shopify theme dev --store my-store

# 3. Lint the code
shopify theme check

# 4. Upload as a new draft theme with a name you will recognize
shopify theme push --unpublished --theme "2026-10-17 header search"
```

The store is remembered after the first command. Publishing is a separate, deliberate step: `shopify theme publish` asks which unpublished theme to publish and asks you to confirm. Pushing to the live theme in a non-interactive run needs `--allow-live`, and `--nodelete` stops remote files being deleted. A `.shopifyignore` file at the theme root keeps unrelated files out of CLI work.

![Shopify's reference page for the theme dev command, describing the local preview address, the editor link, the preview link, and a note that checkout customizations can't be previewed at the local address.](https://cdn.sanity.io/images/9g0lkkr3/production/b433ecb6be49ad1aa951eb6ac2abdc207dbd8b31-1070x660.jpg?w=1400&auto=format)
_Shopify CLI reference page for the theme dev command, shopify.dev, 17 October 2026_

One flag needs a caution. The `theme dev` reference lists `--theme-editor-sync`, which synchronizes theme editor updates into your local files. We have not tested it for this guide and could not confirm when it was introduced, so read the current reference before relying on it.

## Keep custom code in your own files, and apps out of your theme

### Your code, in separate files

Every line you edit inside a theme file can conflict with the next update. A new file you add is one the update won't touch. So add rather than edit:

- Put new markup in a new snippet, called with one `render` line.
- Put new styles in a new asset with a prefix you own, such as `ec-`.
- Comment the one line you add to an original file.

```liquid
{%- comment -%} sections/header.liquid: one added line {%- endcomment -%}
{% render 'ec-announcement', text: section.settings.announcement_text %}
```

```liquid
{%- comment -%}
  snippets/ec-announcement.liquid
  Added 2026-10-17. Reason: shipping note under the header.
  Remove by deleting this file and the render line in sections/header.liquid.
{%- endcomment -%}
{%- if text != blank -%}
  <p class="ec-announcement">{{ text }}</p>
{%- endif -%}
```

```liquid
{{ 'ec-custom.css' | asset_url | stylesheet_tag }}
```

The last line, placed in the layout file, loads a stylesheet that is yours alone. For the CSS itself, see [how to add custom CSS to Shopify](https://www.ecompanda.co/blog/how-to-add-custom-css-to-shopify-the-complete-guide); for Liquid patterns, our [Liquid guide](https://www.ecompanda.co/blog/shopify-liquid-templating-guide-master-shopifys-template).

When Shopify updates a Theme Store theme, the update arrives as a draft named "Updated copy of", and the Help Center says to check that any selectors your custom CSS targets still exist. If your code edits can't be merged, the theme card says so and you copy them across yourself. Separate files make that a short job.

### Apps: app blocks, not pasted snippets

Per the Help Center, apps reach your theme in three ways: an app block you place in a section, an app embed that floats or loads in the background, or code injected into your theme files. Prefer the first two. Shopify's developer documentation says theme app extensions don't edit theme code, which lowers the risk of breaking changes, and merchants place them in the theme editor.

Three rules follow:

1. If an app tells you to paste code into `theme.liquid`, ask first whether a block exists.
2. App blocks need a compatible theme: Online Store 2.0 or later, says the Help Center.
3. Apps don't follow you to a new theme. You re-activate each one after changing theme.

For apps that did inject code, search all files in the code editor for the app's name when you remove it, and check nothing is left.

## Check before you publish: Theme Check and previews

Theme Check is Shopify's linter for the Liquid and JSON in a theme and in theme app extensions. It catches syntax errors, missing templates, unused variables and snippets, deprecated tags and some performance problems. It runs in the code editor, in the Shopify Liquid extension for Visual Studio Code, and from the CLI.

![The top of Shopify's Theme Check documentation page, listing the problems it detects such as syntax errors, missing templates and unused snippets, and the ways to run it.](https://cdn.sanity.io/images/9g0lkkr3/production/e4fa5d3f7f3dcceccb8d8621de56f93bf976357e-780x650.jpg?w=1400&auto=format)
_Shopify's Theme Check documentation page, shopify.dev, 17 October 2026_

From the documentation:

- `shopify theme check` exits with code 1 by default when it finds an error-level issue. `--auto-correct` fixes some issues, and `--init` creates a `.theme-check.yml`.
- Checks that catch real mistakes include `ParserBlockingScript`, `MissingTemplate`, `TranslationKeyExists`, `UndefinedObject` and `ImgWidthAndHeight`.
- `shopify theme push --strict` refuses to push unless Theme Check passes without errors.

```yaml
# .theme-check.yml in the theme root
extends: theme-check:recommended
ignore:
  - node_modules/**
```

If your code lives in GitHub, run the same check on every pull request:

```yaml
name: Theme check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @shopify/cli
      - run: shopify theme check
```

Shopify also publishes a Lighthouse CI GitHub Action that audits a theme's home, product and collection pages on each pull request. It wants a dedicated development store, so it suits teams more than single owners.

### Preview the right way

The Help Center describes two kinds of preview. A visitor preview link works for anyone and expires 2 days after you create it. A merchant preview needs admin login, has access to checkouts, and expires after 30 days. Use the first for feedback from people without admin access and the second to walk through checkout. You can also switch country and language in the preview.

## The QA checklist before you publish

Run this on the draft theme, with the preview open on a real phone. Our [Shopify launch checklist](https://www.ecompanda.co/blog/shopify-launch-checklist) and [ecommerce website checklist](https://www.ecompanda.co/blog/ecommerce-website-checklist) cover a whole store; this one is for a theme change.

| Check | How to test it | What a pass looks like |
| --- | --- | --- |
| Phone layout | Open the preview on a phone. Check header, menu, product page, cart and footer. | Nothing overlaps, scrolls sideways or hides a button. |
| Checkout path | In a merchant preview, add a product, open the cart and reach checkout. Try one product with variants and one without. | You reach checkout without errors, and prices and variants carry through. |
| Forms | Submit the contact form, newsletter signup, search, login and account creation. | Each submits, shows a clear message, and the message arrives. |
| Apps | Open every page type that uses an app block or embed. | Reviews, chat and similar features appear and work. |
| Markets | Switch country and language in the preview. | Currency, translations and links are correct. |
| Speed | Compare changed pages with the live theme in a lab tool. | Largest Contentful Paint 2.5 seconds or less, Interaction to Next Paint 200 ms or less, Cumulative Layout Shift 0.1 or less, at the 75th percentile (web.dev). |
| Accessibility | Tab through with a keyboard, zoom the text, check alt text, headings and form labels. | Focus is always visible, nothing breaks at zoom, every field has a label. |
| Console | Open developer tools on key pages. | No new red errors. |

The speed row uses Google's published "good" thresholds, which are measured on real visitors, so treat a lab test as a warning light only. The accessibility row is a start: the W3C's Easy Checks list quick tests and say plainly that passing them doesn't prove a page is accessible. For depth, see our guides on [theme performance](https://www.ecompanda.co/blog/shopify-theme-performance-optimization-the-complete-guide) and [theme accessibility](https://www.ecompanda.co/blog/shopify-theme-accessibility-guide-building-inclusive-stores).

## Publish, roll back and write it down

### Publishing

Under Draft themes, choose Publish, or publish from the theme editor's top bar. The Help Center says your previous theme moves to Draft themes and none of your changes are lost. That is your first rollback, so keep it until you are sure the new one is sound, and remember the 20-theme limit when you tidy up.

### Three levels of rollback

| Problem | Rollback | Limits |
| --- | --- | --- |
| The whole release is wrong | Republish the previous theme from Draft themes. | Only works if you kept it. Admin edits made to the new theme after publishing are not on the old one. |
| One file is wrong | In the code editor, open the file, use the Timeline panel, pick an earlier version and restore it. | One file at a time, can't recover deleted files, history is finite. Copy the current contents first. |
| A commit is wrong | In GitHub, revert the commit on the connected branch. The theme updates to match. | Admin edits are commits on that branch too, so check what a revert would undo. |

Sources: Shopify Help Center (publishing themes, editing theme code) and the GitHub integration documentation.

### Write it down

Documentation lets someone else, or you in a year, undo a change safely. Keep it short:

- Name themes and branches by date and purpose, such as "2026-10-17 header search".
- Keep a change log: date, who, what, which files, why, and how to remove it.
- Comment added lines in original files, as in the snippet above.
- Note which apps and embeds each page depends on, so a new theme can be rebuilt without guessing.
- Write commit messages that explain why, not only what.

## When to stop customizing and change theme

Every override has a cost that grows. Consider a new theme when:

- **The architecture is behind.** The Help Center describes vintage themes, Online Store 2.0 themes and themes with theme blocks, and says Shopify's free vintage themes receive only security fixes. Sections on every page, app blocks and dynamic sources need Online Store 2.0 or later. For a missing feature, Shopify says to add a new theme that supports it.
- **Updates keep dropping your code.** If every update says your code edits could not be included, the theme is working against you.
- **Your apps don't fit.** If you need app blocks the theme can't host, fix the theme, not the code.
- **You override more than you use.** If most of your CSS undoes the theme's own styles, you are rebuilding the theme.

Changing theme is a project of its own, and the Help Center warns that some apps may not be compatible with a new theme. Our guides to [choosing a theme](https://www.ecompanda.co/blog/how-to-choose-a-shopify-theme-the-definitive-guide), [Online Store 2.0 features](https://www.ecompanda.co/blog/shopify-online-store-2-0-features-everything-you-need-to-know) and [custom theme development](https://www.ecompanda.co/blog/shopify-custom-theme-development) help you decide between an off-the-shelf theme and a custom build.

## Frequently asked questions

### Is it safe to edit my live theme's code?

It is the riskiest option. Mistakes show to customers at once, and Shopify's Help Center recommends duplicating the theme first so you can discard your changes. Make the change on a duplicate or development theme, test it, then publish. The code editor's Timeline can restore one earlier version of a file, but it can't recover deleted files, and history is limited.

### How many themes can I keep, and do development themes count?

You can add up to 20 themes to your admin, with one published. Development themes made by Shopify CLI don't count toward that limit. They are temporary, and Shopify deletes them after seven days of inactivity or when you run `shopify auth logout`. If you need a preview link that survives, push to an unpublished theme instead.

### Will my customizations survive a theme update?

Edits made in the theme editor are copied to the updated theme. Code edits are included only if they don't conflict with the update, and the theme card tells you whether they were. The update arrives as a draft, so you review it before publishing. Keep custom code in separate files so you can re-apply it quickly.

### Do I need GitHub to customize a theme safely?

No. Duplicating a theme, working on drafts and keeping a change log already give you a safety net. GitHub adds a full history, review before changes go live, and the ability to revert a single change. If more than one person touches the theme, we think it pays for itself quickly.

### Can I preview checkout changes before publishing?

Not in the local CLI preview: Shopify's `theme dev` reference says checkout customizations can't be previewed at the local address. The Help Center says a merchant preview, which needs admin login, has access to checkouts. Use that to walk through checkout on the draft theme.

## Where we can help

We build and maintain Shopify themes, and we use this workflow on every store we touch. If you want a change made safely, a theme reviewed before an update, or a view on whether to customize or replace, see our [services](https://www.ecompanda.co/services) or [get in touch](https://www.ecompanda.co/contact).

## Related

- [Shopify metafields and metaobjects, explained](https://www.ecompanda.co/blog/shopify-metafields-complete-guide-unlock-custom-data)
- [Shopify Liquid: a practical guide for theme editors](https://www.ecompanda.co/blog/shopify-liquid-templating-guide-master-shopifys-template)
- [Shopify Online Store 2.0: what it is and what changed](https://www.ecompanda.co/blog/shopify-online-store-2-0-features-everything-you-need-to-know)

---

Canonical HTML version: https://www.ecompanda.co/blog/best-practices-for-shopify-theme-customization