Skip to main content
Version: 0.2.x

Optimization

Critical CSS​

Critical CSS are styles which are loaded before your page is rendered. Including critical CSS in your theme ensures the above-the-fold content renders quickly, correctly, with minimal movement during rendering. This is especially important in SALVO-TS, where your component's stylesheets may be loaded asynchronously.

You can mark styles to include in your critical css using the @media critical custom media query:

assets/styles/global/header.scss
scss
@media critical {
    .page-header {
        display: flex;
        align-items: center;
    }
}
assets/styles/global/header.scss
scss
@media critical {
    .page-header {
        display: flex;
        align-items: center;
    }
}

This can be used in component CSS too, and follows the same conventions as other media rules - it can be nested or combined with other queries:

src/components/ProductGallery.scss
scss
product-gallery {
    @media critical {
        display: flex;
        align-items: center;
        background: gray;
        > .product-gallery__child {
            display: none;
            @media screen and (min-width: 768px) {
                display: block;
            }
        }
        > .product-gallery__child:first-child {
            display: block;
        }
    }
    cursor: pointer;
    &:focus {
        box-shadow: 1px 1px 1px 1px rgba(0,255,255, 0.4);
    }
    > .product-gallery__navigation {
        display: none;
        @media screen and (min-width: 768px) {
            display: flex;
        }
    }
}
src/components/ProductGallery.scss
scss
product-gallery {
    @media critical {
        display: flex;
        align-items: center;
        background: gray;
        > .product-gallery__child {
            display: none;
            @media screen and (min-width: 768px) {
                display: block;
            }
        }
        > .product-gallery__child:first-child {
            display: block;
        }
    }
    cursor: pointer;
    &:focus {
        box-shadow: 1px 1px 1px 1px rgba(0,255,255, 0.4);
    }
    > .product-gallery__navigation {
        display: none;
        @media screen and (min-width: 768px) {
            display: flex;
        }
    }
}

Critical CSS only output​

Troubleshooting critical styles can be difficult when the rest of your non-critical CSS keeps getting in the way. To make this easier, you can set optimizations.includeCriticalStyles to "only", which will build your theme without including any non-critical styles. This means when you load a page it will include only your critical styles.

info

This doesn't prevent any CSS which is injected by Shopify Apps, the theme customizer, or other external sources from loading. For the most reliable experience, consider using a browser extension like uMatrix to block external JS and stylesheets while working on your critical styles.

danger

This setting is intended for development and should never be used to build a public release.

Note the compiler will not prevent you from using this setting in a production build, to allow for testing the impact of production-mode settings like minification. You must ensure it's disabled before building your theme for release.

Minification​

Minification of JS and CSS is enabled by default in production builds. If you would like to minimize dev builds too, set optimizations.minify to 'always'.

If you encounter issues with the minification process, it can be disabled by setting optimizations.minify to 'never'.

Component preloading​

By default all components' JS and CSS are loaded on demand. If you have global components which are always included you can add them to optimizations.preloadComponents like ["SiteHeader", "SiteFooter"] to ensure that preload tags are always included for these components, which may speed up component loading.

You can set optimizations.eagerComponentPreloading to true to attempt to use an optimization which includes modulepreload tags in Liquid based on page content. This is not guarenteed to work and you should not rely on it for your components to load in a particular order.

Component CSS​

By default component CSS is either inlined into the component JS if it is below a particular size, otherwise it is built as a separate file which components will inject a stylesheet link to load. You can override this behavior by setting components.sass.cssBuildMode to one of "inline" (force always inline), "async" (force always as separate file). You may also set components.sass.cssInlineLimit to adjust the default limit at which CSS gets inlined vs. emitted separately.

Preview bar​

The preview bar can be completely disabled by setting optimizations.previewBar to "block".

You can replace the default preview bar with a less obstructive version (which generates non-shopifypreview preview links) can be enabled by setting optimizations.previewBar to "mini" (this is based on @Simon's userscript.)

SVG Icon optimization​

SVG icons are optimized by default using svgo.

If you want to disable all customizations, set optimizations.icons to false. Alternatively if you want to continue optimizing SVG icons but avoid converting colors to currentColor, set optimizations.icons.convertToCurrentColor to false.

Adding extra attributes without optimization enabled

Disabling SVG icon optimizations will prevent you from passing extra attributes such as class names to the {! icon !} macro. Instead, you must include them in the original SVGs manually.

CWV Overlay​

The CWV overlay displays performance measurements in an overlay on any unpublished theme. The overlay is enabled by default, but if you wish to disable it you can set optimizations.cwvOverlay to false.

Dev build reminder​

The dev build reminder is an overlay which appears on themes built in development mode. When previewing an unpublished theme that was built in dev mode, it appears as as small banner in the bottom-right of the screen. Hovering over the banner will move it to the top of your screen and vice-versa.

If you publish a theme which was build in dev mode, the banner will change to a full-screen overlay which makes the site inaccessible. Do not publish themes build in dev mode.

If you must override this behavior, configure by through optimizations.devBuildReminder (see configuration.)

Preloader overlay​

Adding a very brief white overlay to the screen can help with CLS scores in Lighthouse. You can include this automatically by setting optimizations.preloader to "blank".

Setting optimizations.preloader to "pseudo" will enable an alternative overlay which may make CLS, FCP, and LCP scores more consistent. You should only enable this if you are absolutely sure you have already resolved these concerns (i.e. loading the site with 3G throttling, no element moves position in any way, and the largest above-the-fold element loads first and quickly) and you are having trouble with app loading interfering with Lighthouse measurements.