Your customers see the old version of the store: browser cache and versioning

You have fixed a design bug on mobile, checked that it looks right and consider the matter closed. The next day a customer sends you a screenshot with the page out of alignment, exactly as it was before. You cannot reproduce it. The customer is not mistaken: their browser is still using the old stylesheet it saved the last time they visited the store.

It is one of the most puzzling problems in maintaining a store, because it never happens to the person who makes the change. Let us look at why it occurs and how to avoid it.

Why the browser stores files

So that pages load quickly, the browser keeps a copy of files that do not change often: stylesheets, scripts, images and fonts. The next time it needs them, it uses its copy instead of requesting them from the server. How long it keeps them is decided by the cache headers the server sends with each file.

For a store, keeping those files for a long time is good: fewer requests, faster pages, less load on the server. The problem arises when you change one of them and its address stays the same. The browser has no way of knowing there is a new version, and keeps using the one it has until it expires.

The symptoms

• A broken or half-applied layout only for some customers.
• A button that does nothing because the HTML is new but the JavaScript is old (or the other way round).
• JavaScript errors in the console that do not appear in your browser.
• Complaints that go away on their own after a few days, when the copies expire.
• The developer's classic "it works for me", after reloading with the cache cleared.

It is not just the browser

Between your server and the customer there may be several layers that keep copies:

• PrestaShop's cache of combined files. If you have enabled the option to combine, compress and cache CSS and JS, the store serves files generated from yours. If you change a source file and the combined version is not regenerated, nobody sees the change, not even you.
• Smarty's template cache, if you have changed a template.
• A page cache, in a module or on the server, which stores the HTML with the old addresses.
• A CDN or proxy in front of the store, with its own copy of the files.
• Each customer's browser.

You control the first four: clearing them is part of any design change. Not the last one: you cannot ask every customer to clear their cache.

The solution: the address changes when the file changes

The standard technique is called versioning (or cache busting). It means the file's address includes something that changes every time its content changes. For example, by adding a parameter: custom.css?v=20 becomes custom.css?v=21. To the browser it is a new address, so it downloads it; and as long as it does not change, it can keep it for as long as it likes.

There are several ways to work out that marker:

• By the file's modification date. Automatic: every time you save the file, it changes. Only what has changed is downloaded again.
• By a fingerprint of the content. Just as automatic and more precise, but it has to be calculated.
• A global version number that you bump with every deployment. Everything is downloaded again, even if only one file has changed.

When PrestaShop combines and compresses files, it already generates new names for the combined file when regenerating it. But not every store uses that option (it sometimes causes problems with the loading order of certain modules) and it does not cover files loaded individually.

Watch out for dates during deployments

Versioning by modification date has a catch: if you upload files with a tool that preserves the original date (some FTP programs, some ways of deploying or restoring backups), the file changes but its date does not, and the version marker stays the same. In those cases you need to be able to force a new version by hand after deploying.

What if I shorten the cache time?

That is the temptation when the problem keeps recurring: configure the server so that the browser keeps CSS and JS for only a few minutes, or always checks for a new version. It works, but you pay for it on every visit: more requests, more waiting on mobile and more load on the server, even for files that do not change for months. With versioning you can do exactly the opposite: keep long cache times, which is what favours speed, because when a file changes, its address changes too.

What you should ensure is that the HTML of the pages is not kept for long in the browser or in intermediate layers, because it is the HTML that carries the addresses with the version. If the old HTML is still cached, it will keep requesting the old files even if they are versioned.

What to do after every design change

1. Clear PrestaShop's cache (templates and combined files) from Advanced Parameters → Performance.
2. If you have a page cache or CDN, purge them.
3. Check that the addresses of the CSS and JS files you have changed carry a new version marker (in the page source code).
4. Test in a browser in which you had already visited the store before the change, without clearing its cache: that is how a real customer sees it.
5. Test on mobile, which tends to hold older copies.

How to solve it in PrestaShop

Rekire Cache Buster adds a version marker (?v=) to each local CSS and JS file on the front office, so that the browser downloads the new one as soon as it changes. It has two modes: automatic, with the version taken from each file's modification date, or manual, with a single token that you change yourself. You can enable it for CSS, for JS or for both, and the Force reload now button makes all visitors download the CSS and JS again after a deployment, which is what you need if your way of uploading files preserves their dates. It does not touch files served from another domain or CDN, or those that already carry their own version, and it does not combine or compress anything, so it does not alter the loading order. Compatible with PrestaShop 1.7, 8 and 9.