Offline Cache

Configuring the Cache

The offline cache stores files on the device so pages work without a connection.

Where to find it

Architect Panel → Layout & Pages:

• Dependencies — the files the site loads, and what the offline cache is built from

Architect Panel → Configuration:

• Site Settings — the Progressive Web App and Service Workers option groups

Where the list comes from

The cached file list is built from the site’s registered dependencies, filtered by scope. Each dependency names a URL, a type, whether it was added automatically, and which scope it belongs to — the main website, the web app, the admin panel, or all of them.

So the cache is not configured separately; it follows from what your site already declares it needs.

Images are included automatically

Everything under the images directory is added to the cache without being listed. That is convenient and it is worth knowing, because a large image library becomes a large first-load download.

If your images directory has accumulated years of unused files, the offline cache is a reason to clear them out.

Scope decides what goes where

A dependency scoped to everything is cached in every scope. One scoped to the web app is cached only there. Getting this right keeps each scope’s cache to what that scope actually needs.

Cache-first, then network

The service worker looks in the cache first, then goes to the network and stores what it finds. That is what makes repeat visits fast and offline use possible.

It is also what makes stale content possible, which is the trade you are accepting.

Failures are per file

If caching the whole list at once fails, files are cached one at a time so one bad entry does not lose the lot. A URL that cannot be fetched is skipped with a warning rather than breaking the install.

Which means a broken dependency is quietly not cached — check the browser console when something is not working offline.

Keep the list honest

Dependencies accumulate. Files for a feature you removed, a library replaced two years ago, a script nothing loads — all still cached, all still downloaded on first visit.

A periodic review of the dependency list is worth it for load time alone.

Version changes matter

When you deploy new assets, users with an existing cache may keep the old ones for a while. Plan for that: either version your asset filenames so new ones are genuinely new, or expect a lag.

Test properly offline

Load the app, then put the device into flight mode and use it. That is the only real test, and it will show immediately which parts work and which are blank.

Worked example

An organisation reviewed its dependency list before enabling caching and removed nineteen entries for retired features, along with several hundred unused images. First load fell substantially. Offline behaviour was tested in flight mode on a real phone.

Recommendations

• Review dependencies before enabling the cache.
• Clear out unused images — they are cached automatically.
• Scope dependencies rather than caching everything everywhere.
• Test in flight mode on a real device.

What Works Offline

Offline caching stores files. It does not store your data, and the difference decides what actually works.

Where to find it

Architect Panel → Configuration:

• Site Settings — the Progressive Web App and Service Workers option groups

Architect Panel → Layout & Pages:

• Dependencies — the files the site loads, and what the offline cache is built from

What survives offline

• Cached pages and assets — the interface loads.
• Images already cached.
• Scripts and styles, so the application looks and behaves normally.

What does not

• Anything read from the database. Lists, records, search results — all of it needs the server.
• Saving anything. A submission with no connection does not queue itself.
• Signing in.
• Anything from another service.

So an offline web app shows its shell and very little else. Understanding that prevents promising something the technology does not do.

Say so to users

The dangerous outcome is a user who believes the app works offline, does an hour of work in a tunnel, and loses it. That is worse than an app that plainly refuses.

Where a connection is genuinely lost, the honest thing is to say so on screen.

It is mostly about speed

Which is the real benefit and is undersold. Cached assets mean the app loads immediately on repeat visits and survives a brief connection drop without a browser error page.

For most organisations that is the whole value, and it is worth having.

Staleness is the cost

Cached files are served ahead of the network, so a user can be running yesterday’s interface. Usually harmless; occasionally the reason one person sees a bug nobody else can reproduce.

"Have they still got an old cache" belongs early in your support script.

If you need real offline working

Records available and changes queued while disconnected, then synchronised — that is the native mobile app builder, which has an explicit offline mode and a retry window for queued operations.

A progressive web app is the right tool for a fast, installable interface. It is not the right tool for genuinely disconnected working.

Test what a user actually sees

Open the app offline from cold and look. Whatever appears is what your users will see in a lift, on a train or in a basement, and it is usually less than expected.

Worked example

An organisation enabled caching for speed rather than offline working, tested the app from cold in flight mode, and added a banner shown when the connection is lost. Support scripts now begin by asking whether the app has been closed and reopened.

Recommendations

• Treat it as a speed feature, not an offline one.
• Tell users when the connection is lost.
• Ask about stale caches early in support.
• Use the mobile app if you need real disconnected working.