Theme performance

Theme developers should strive to make beautiful and cohesive experiences for sellers that are also considerate of performance. Having themes that render quickly enhance the buyer’s experience and reduce visitor drop off.

Performance can apply to many surface areas such as in-browser performance and initial serverside page load. This guide will cover how a theme developer can utilize platform features to ensure higher theme performance.

Render caching

When a page is rendered on a published site (non-preview), the resulting HTML is cached by our rendering platform. On every subsequent page visit with the same parameters, our platform will respond with the previously cached result in order to cut down on render time and overall server load. The cached output includes any resources that were used to render the HTML.

The render cache for a specific page URI is invalidated upon site publish or relevant catalog change events.

Uncacheable resources

Certain resources used within a template will flag your page as uncacheable. This means that every page render including the uncacheable template will be rendered from scratch and will not benefit from HTML response caching.

Refer to this guide on how to load uncacheable resources with the template API.

Query parameter allowlist

The query parameter allowlist theme configuration allows the theme to define which query parameters impact the server-side render.

Refer to the query_param_allowlist documentation for more details.

Cookie-based query redirects is a feature that can be enabled when query_param_allowlist is defined. It helps site visitors retain previous UI selections if those values are tracked via query parameters.

For more information, see Cookie-based query redirects.

Browser performance

To maximize browser performance for Square Online theme development, it is important to limit the amount of work that the browser is responsible for by rendering as much server-side content as possible.

Anything that is shown as a result of user interaction should ideally be omitted from the initial page load, but rendered through the Template API. This approach enables the platform to serve the same cached content to different buyer sessions. This will reduce the amount of rendering required and improve page load times.

Example

Parent template

<body>
    <button id="modal-opener">
        Open Locations
    </button>

    <div id="locations-wrapper" class="modal">
    </div>
</body>
<script>
    document.addEventListener('DOMContentLoaded', () => {
        const btn = document.getElementById('modal-opener');

        btn.onclick = async () => {
            const text = await window.SquareWebSDK.template.getTemplate({
                template: 'components/partials/location-modal',
                props: {
                    locations: {{ locationQuery | json_encode }}
                },
            })

            document.getElementById('locations-wrapper').innerHTML = text;
        }
    });
</script>

{% schema %}
{
	"locationQuery": {
		"type": "location-list-query"
	}
}
{% endschema %}

Locations-modal template

{% for location in locations %}
    <p> ID: {{ location.id }}</p>
{% endfor %}

{% schema %}
{
	"locations": {
		"type": "location-list",
		"optional": true
	}
}
{% endschema %}