Theme Cache Configs

After render of a specific route (including query parameters), our application saves the rendered result in a cache. This cached value is re-used for every subsequent request to the same URI. Theme developers can leverage theme configs that allow for the cacheability of its rendered content to be improved.

Query param allowlist

name: query_param_allowlist

type: string[]

When this config is present, the rendering engine will consider the query parameters within the array when building the cache for a page. The theme developer is expected to provide all query parameters that are used for server-side rendering in this array. Any query parameters within a request that are not within the allowlist will be ignored for cache generation. It’s beneficial to only enter query parameters that affect the server-side render into the query parameter allowlist. Those that are used only within the context of client-side logic should be omitted

Optionally, the theme developer can set the array as empty to signify that no query parameters should be used when building the rendered page cache. If no allowlist is provided, all query parameters will be utilized for the rendered cache.

Example A:

config/global.json
{
    "query_param_allowlist": [
        "location_id",
        "fulfillment"
    ]
}

This example configuration tells the rendering engine that it should only consider location_id and fulfillment query parameters for the rendered cache. All other query parameters will be omitted.

This way a request to mysite.com?location_id=321 will utilize the same page rendered cache as mysite.com?location_id=321&my_junk_query_param=foo. Keep in mind that a new cache will be generated for differing values of allowlisted query parameters (e.g. ?location_id=789).

Example B:

config/global.json
{
    "query_param_allowlist": []
}

In this example, any query parameters provided in the request will be omitted from the rendered cache, thus mysite.com?foo=bar will use the same rendered cache as mysite.com?baz=foo.

When enabled and the query_param_allowlist is populated, our application will record query parameter allowlist values on the requested URL and store them within a browser cookie. Any request on the same session that is missing an allowlisted query param that has a value in the cookie will trigger a redirect to the same url with the query param value extracted from the cookie.

This redirect will allow the site visitor to encounter more render cache hits, resulting in faster page delivery time and the rendering of more meaningful page content without the need to re-enter information.

The cookie based redirects can be enabled through a theme global config

config/global.json
{
    "cookie_redirects" : {
        "enabled": true
    },
    "query_param_allowlist": [
        ...
    ]
}

Usage example:

A new site visitor comes to a restaurant website’s /order page and chooses the location that they would like to order from. The theme then appends the location_id=123 query parameter to the page URI. The underlying theme has a query_param_allowlist containing the location_id in its array.

config/global.json
{
    "cookie_redirects" : {
        "enabled": true
    },
    "query_param_allowlist": [
        "location_id"
    ]
}

When the page render request is made with the location_id query param, the key and value are saved in a cookie that is temporarily persisted until the same buyer session makes a request with a different location_id query param value or the cookie expires.

If the buyer re-visits the restaurant website’s /order path again without the location_id query param, our application will see that the buyer previously had chosen location_id=123. It will then trigger a redirect to the same URL but with location_id=123 appended.

By default, the query parameters are only automatically scoped to the path that it was initially set on.

For example, if a buyer visits /order?location_id=123, the location_id query parameter value of 123 is only automatically re-applied on visits to the /order path.

In the event where a theme intends to share query parameter key values between all pages, a global theme config can be provided that will trigger the cookie based redirects feature for all pages.

config/global.json
{
    "cookie_redirects" : {
        "enabled": true,
        "all_paths": true
    },
    "query_param_allowlist": [
        "location_id"
    ]
}

When cookie_redirects.all_paths is set to true, the query parameter key and value are no longer limited to a single path.