One Last Hint: Eager-Load All the Things

The Blitz Hints utility, first introduced three years ago, has been retired in 5.10.0.

The Blitz Hints utility provided templating performance hints for eager-loading elements. This was a hugely popular and useful tool for discovering and optimising element queries in Twig templates.

Why Now? #

Since the release of Craft 5 – in which Matrix blocks became nested entries, and CKEditor added the ability to create nested entries – detecting eager-loading opportunities has become increasingly more complex. Many Craft 5 minor releases included subtle changes to element queries, resulting in Blitz Hints occasionally reporting false negatives or false positives. 

Keeping up with the changes became a game of cat-and-mouse, which led to the decision to retire Blitz Hints. 

What’s the Alternative? #

The alternative is to learn and use good templating practices. Fortunately, there’s a good rule of thumb:

Use lazy eager-loading for all relational fields (using .eagerly()). Use .with() for native attributes and image transforms that cannot be lazy eager-loaded.

Use the .eagerly() query param whenever loading relational fields such as related and nested entries, and related assets, categories, users, etc.

{% set articles = craft.entries.section('articles').all() %}
{% for article in articles %}
    {% set relatedEntries = article.entriesField.eagerly().all() %}
    {% set nestedEntries = article.matrixField.eagerly().all() %}
    {% set relatedAssets = article.assetsField.eagerly().all() %}
{% endfor %}

Use the .with() query param to eager-load ​“native” element attributes such as entry authors, user addresses, user photos, etc.

{% set articles = craft.entries.section('articles').with('authors').all() %}
{% for article in articles %}
    {% set authors = article.authors.all() %}
{% endfor %}

You can either use the .with() or the withTransforms query param to eager-load image transforms.

{% set articles = craft.entries.section('articles')
    .with([
        ['assetsField', {
            withTransforms: ['heroImage']
        }]
    ])
    .all() 
%}

Why is Lazy Eager-Loading not enabled by default? #

I first asked Brandon Kelly this at Dot All 2023, during the Craft 5 developer preview. Because eager-loaded elements are returned as a Collection rather than an array, enabling lazy eager-loading by default would constitute a breaking change.

Personally, I see no downside to making this the default in Craft 6, and have proposed exactly that in this GitHub discussion.

I even explored adding a setting to Blitz to enable it for you by default, but it’s not currently possible due to the lack of available events.

Conclusion #

Most importantly, retiring Blitz Hints simplifies things going forward, and allows us to focus on optimising the internals to ensure that Blitz continues to deliver fast, reliable performance out of the box.