File transformation best practices for Shopify themes
File transformations improve the developer experience by letting you write and maintain code using your preferred strategies and build tools, and ship compiled code that is optimized for browser runtime.
For example, you might want to divide your stylesheets into multiple files, each scoped to a particular UI element, which makes them easier to maintain. However, loading a large number of small stylesheets is slower than loading one or two larger stylesheets. You can use file transformations to automate the process of combining these smaller, scoped stylesheets into fewer, larger bundles.
You can transform files as part of a build process, and then upload your compiled code as a theme that can be accessed in the Shopify admin.
Below are some examples of file transformations that theme developers might want to perform:
| File transformation | Benefit |
|---|---|
| Custom file structure > Shopify theme file structure | Code maintenance flexibility |
| SCSS > CSS | Write in SCSS, output Shopify-compatible CSS |
| SVG > snippet | Include SVGs inline in HTML |
| PostCSS transformations (e.g. Autoprefixer, cssnano, tailwindcss) | Linting, variables, transpiling, browser compatibility |
| Section folders > section files | Build sections in separate Liquid, JS, CSS, and JSON files |
| Automated calculation and inlining of critical styles | Avoid load-blocking CSS resources |
| Optimized JavaScript bundles | Reduced load times, smaller file sizes |
| JavaScript, CSS, and HTML minification | Reduced load times, smaller file sizes |
If you want to perform transformations on your files, then you need to decide how you want to manage both the source code and the transformed, or compiled, code. To learn about the options, and which options can be used with Shopify tools, refer to Version control best practices for Shopify themes.
You can also consider using just-in-time (JIT) file transformations to reduce the need to track changes to compiled code. JIT transformations can deliver optimized dependencies and resources at runtime, allowing for a unified code base that doesn't need to be backfilled.
Compiled code and merchant or app customizations
Anchor link to section titled "Compiled code and merchant or app customizations"After a theme is uploaded to Shopify, merchants can customize it using the theme editor or the code editor. Apps might also change the theme code through the Asset REST Admin API resource. This can lead to situations where compiled code has been altered, but source code hasn't been updated.
You might need to identify changes to the compiled code, and then manually backfill those changes into your source code so the changes persist the next time the code is compiled. This is a particular risk if you are a Partner or merchant developer who performs ongoing customizations to a merchant's theme. You should consider the impact of merchant or app customizations when planning your file transformation and version control strategy.
Backfilling changes to compiled code
Anchor link to section titled "Backfilling changes to compiled code"When a change is made to a compiled file and the theme is connected to GitHub, then the change is added to the theme's GitHub repo as a commit. You can use this commit to identify and backfill merchant changes.
The following is an example of identifying and backfilling a change to a theme that's connected to version control using the Shopify GitHub integration.
Step 1: The developer writes source code and compiles it
Anchor link to section titled "Step 1: The developer writes source code and compiles it"You create the following scoped JavaScript resources for a theme.
These three files are bundled for optimized delivery, resulting in the following file:
These files are all committed to the GitHub repo, and then index.bundle.js is synced with the store using the Shopify GitHub integration.
index.bundle.js is called inside of a Liquid template:
This store or theme is handed off to the merchant.
Step 2: The merchant edits compiled code
Anchor link to section titled "Step 2: The merchant edits compiled code"When the merchant starts using the theme, they need to make a change to the compiled JS bundle using the code editor in the Shopify admin:
This change is synced to the theme's associated GitHub repo as a commit.
Step 3: The developer identifies changes to compiled code and backfills them
Anchor link to section titled "Step 3: The developer identifies changes to compiled code and backfills them"When the merchant contacts you to add another feature to your theme, you can see the commit from the Shopify admin in the repo.
Because the change was made to the compiled index.bundle.js, this change will disappear when the file is recompiled, unless a corresponding change is made to the source files.
To make sure changes made to compiled code persist after the code is recompiled, you can manually backport the change into the source code. In this case, you can modify index.js:
Just-in-time file transformations
Anchor link to section titled "Just-in-time file transformations"Many transformations are one-way: you can transform source code into compiled code, but you can't transform compiled code into source code. Most code management strategies for Shopify themes involve tracking changes to compiled code and backfilling source code. This is because the code a merchant sees is often the result of a file transformation, and a merchant might edit the code or install code-injecting apps as a part of running a store.
You can use just-in-time (JIT) file transformations for some of your common file transformation tasks. JIT transformations move the functionality of installed developer tools to on-demand services that can generate an optimized runtime file from source code.
When you remove the need to perform certain types of file transformations, you can further reduce or even eliminate the number of compiled files that you need to create, track and maintain. Merchants can edit source code rather than compiled code, allowing for a unified code base that doesn't need to be backfilled.
Common uses for JIT transformations include JavaScript minification, CSS optimization and minification, and third-party dependency management.
- This method is compatible with the Shopify GitHub integration.
- Maintenance is performed by service owners.
- This method works within Shopify's supported theme file structure.
- Merchants can work on source files, resulting in reduced backfilling.
Shopify minification
Anchor link to section titled "Shopify minification"Shopify automatically minifies CSS and JavaScript files. For instance, you can include a CSS file such as main.css in your asset folder. Shopify compiles and sends a minified version of it, which updates every time the source file changes.