How Caching on the Web Works

A Practical Guide for Developers, Clients, and Anyone Who’s Ever Been Told “I Still See the Old Version”

Caching is one of the most important performance tools on the web—but it's also one of the most common sources of confusion, stale content, and client review issues. If you’ve ever deployed a change only to hear “It still looks the same on my phone,” you’ve experienced the dark side of caching.

This guide breaks down what caching actually does, why it helps, why it hurts during development, and how to work around the most common problems in WordPress, React/Vue apps, and static websites.

How Caching Works

Caching is ultimately about avoiding unnecessary work. If a browser or server already has a file and believes it’s still valid, it won’t download it again. This saves time, bandwidth, and server resources resulting in faster load times and lower costs.

Two major categories:

• Server Cache (CDN, page cache, object cache)
• Local Browser Cache (stored on the user’s device)

Server Cache

Server-side caching reduces the work your backend must perform and often keeps the request from hitting your application at all. Common types include:

Page Cache (HTML caching)

Stores a ready-made version of a page.
Used by: WP Engine, Pantheon, SiteGround, Cloudflare APO, Varnish.

Object Cache

Stores computed values or query results.
Tools: Redis, Memcached, WordPress Object Cache.

Opcode Cache

PHP’s OPcache caches compiled PHP bytecode to speed up execution.

CDN Edge Cache

CDNs store static files across global servers and serve them before the request even reaches your host.

Local Browser Cache

Often times the culprit of caching issues when developing or reviewing changes is the browser cache. Browsers store assets such as images, CSS, JS, fonts, and sometimes HTML. This is controlled by HTTP headers sent from the server.

Rules are determined by HTTP caching headers:

• Cache-Control
• ETag
• Last-Modified
• Expires

If the browser thinks a file hasn’t changed, it won’t download it again.

iOS Safari is especially aggressive about caching, which leads to the classic “works on my machine but not on the client’s phone” problem. Safari’s caching can be more aggressive or persistent than other browsers, leading to stale content that doesn’t update when expected.¹

Benefits of Cache

Caching improves:

• Speed — faster page loads
• Performance — lower server load
• Cost — less bandwidth and CPU usage
• User Experience — smoother repeat visits

Development Headaches

Caching causes issues when your code changes but the browser, server, or CDN refuses to fetch the new version.

Errors and Issues

Common caching-related problems:

• Deployed changes don’t show up
• Clients see older versions of layouts or scripts
• CDN continues serving stale HTML or JS/CSS
• Mismatched versions break layout or functionality
• iOS devices cling to cached assets longer than expected

Clients Seeing Old Versions During Reviews

One common scenario that frustrates developers and clients alike is when you deploy a change, verify it looks correct on your machine, let the client know it's ready to review, but the client still sees the old version.

You push a change → it looks correct on your machine → the client checks on their phone → they still see the old version.

This happens because browsers use the URL as a cache key.
If the URL doesn't change, the browser assumes the file hasn’t changed—even if you redeployed it.

Hence the need for cache busting.

Workarounds and Fixes

Here are proven ways to eliminate caching issues for static sites, WordPress, and React/Vue applications.

Client Communication

Setting expectations early saves hours of confusion.

Explain to clients:

• Their device may cache old versions of files
• Refreshing or using incognito can help
• iOS Safari is particularly sticky with cache
• You handle cache-busting automatically during deployment

WordPress Solution: Theme Versioning

WordPress makes cache-busting easy by using the theme version from style.css as the version for CSS/JS.

In style.css:

Theme Name: My Custom Theme
Version: 1.4.0

In functions.php:

function theme_assets() {
    $theme   = wp_get_theme();
    $version = $theme->get( 'Version' );

    wp_enqueue_style(
        'theme-style',
        get_stylesheet_directory_uri() . '/assets/css/style.css',
        [],
        $version
    );

    wp_enqueue_script(
        'theme-js',
        get_stylesheet_directory_uri() . '/assets/js/main.js',
        [],
        $version,
        true
    );
}
add_action( 'wp_enqueue_scripts', 'theme_assets' );

This generates:

style.css?ver=1.4.0
main.js?ver=1.4.0

Bump the theme version in style.css, browsers will see a new URL, it will download the new file.

This fixes most iOS/Safari caching issues.

React/Vue Apps: Hashed Build Files

Modern JS build systems automatically create hashed filenames:

app.48bf2e7.js
style.a9e23c1.css
logo.239afbc1.png

Each build generates brand-new filenames. Benefits:

• Browsers cache files “forever”
• Users automatically receive updated versions
• CDNs safely cache without risk of stale assets
• No manual versioning required

This is the ideal approach for React, Vue, Next.js, Nuxt, Vite, Astro, etc.

Static Sites: Cache-Busting Options

Static sites don’t have a backend, but still need cache-busting. Here are the options:

1. Version Query Strings

Simple and effective for small sites or Webflow exports.

2. Hashed Filenames With a Build Step

Use a static site generator or build tool to create hashed filenames. Here are some popular tools that support this:

• Vite
• Parcel
• Webpack

Produces:

style.91e82b1.css
app.127dd92.js

3. File Modification (mtime) Versioning

Or in Node:

const version = fs.statSync("css/style.css").mtimeMs;

Conclusion

Caching is essential for fast, efficient websites, but it can disrupt development and review cycles if you don't plan for it.

Use these techniques to avoid stale content issues:

• WordPress: bump theme version & enqueue asset versions
• React/Vue: rely on hashed build filenames
• Static Sites: use query strings, hashing, or filemtime
• Client Communication: set expectations early

With a solid cache-busting workflow, you can ensure clients always see the latest version—and enjoy all the performance benefits of caching.