Skip to content

Concept in Performance

The app shell model

Published Updated

Widely available since 2018-04W3C draft

The app shell model precaches the minimal HTML, CSS, JavaScript, and icons needed to draw a PWA frame, so repeat visits can paint without waiting for the network. A service worker caches this shell at install and serves it from Cache Storage on later navigations. The content is fetched or read from a data cache after the shell renders.

The shell contains the interface shared across routes: the header, navigation, layout skeleton, and the scripts that render content into it. Chrome’s app shell guide defines it as the minimal HTML, CSS, and JavaScript that power the interface, with content loaded dynamically. A build can list those stable resources for the service worker’s install event. A fetch handler can then answer navigation requests with the cached shell document, while the page script requests route data (The App Shell Model, developer.chrome.com).

Cache Storage and the HTTP cache are separate stores. The Service Workers specification defines Cache Storage as a request and response store and exposes it to service workers. Entries are selected by request, and application code decides when to create, replace, or delete a named cache. A name such as app-shell-v3 is defined by the application; browsers do not reserve it. Keeping shell resources in their own named cache lets an activation handler remove an old shell without selecting unrelated runtime responses.

A shell cache can be named with a version (app-shell-v3). A new deploy changes the name, the new service worker’s install fills the new cache, and its activate handler can delete caches whose names start with the shell prefix but differ from the current name. Scoping the deletion to that prefix leaves differently named runtime and data caches (articles, images) outside the deletion list. The Service Workers specification defines installation, waiting, activation, and control as separate lifecycle stages; skipWaiting() and clients.claim() alter when the new worker advances and controls clients.

The shell separates interface resources from content requests. Chrome’s guide presents both client-side and server-side rendering approaches and notes that the shell is not the whole application. With client-side rendering, the shell can come from a cache while route content still comes from an API. With server-side rendering, navigation can return HTML that already contains route content. An application can also use the cached shell as its offline navigation response and use server-rendered responses while the network is available.

This separation requires an explicit content failure state. A cached shell does not imply that the API response or route data is cached. The page should display an offline message or cached content when its data request fails. The fetch handler below also falls back to the navigation request when /shell.html is absent, so a missing shell entry does not turn the cache lookup into an empty response.

The model is a pattern over the Service Worker API and Cache Storage. There is no separate appShell browser feature; support follows those APIs. The compatibility dataset records Service Worker support from Chrome 40, Edge 17, Firefox 44, and Safari 11.1; its Safari on iOS entry mirrors the Safari data (BCD api.ServiceWorker). Without navigator.serviceWorker, the registration example sets its network fallback marker instead of trying to install the worker. See the measured service worker compatibility data before choosing the fallback for a supported browser set.

A service worker precaches and serves the shell; the page registers the worker.

Precaching the shell and serving navigations from it

Section titled “Precaching the shell and serving navigations from it”

The install step caches the shell document and assets; the fetch handler answers navigation requests with the shell and everything else cache-first with a network fallback.

const SHELL = 'app-shell-v3';
const SHELL_ASSETS = ['/shell.html', '/styles/app.css', '/scripts/app.js', '/icons/icon-192.png'];
self.addEventListener('install', (event) => {
event.waitUntil(caches.open(SHELL).then((cache) => cache.addAll(SHELL_ASSETS)));
});
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys().then((keys) =>
Promise.all(keys.filter((k) => k.startsWith('app-shell-') && k !== SHELL).map((k) => caches.delete(k)))
)
);
});
self.addEventListener('fetch', (event) => {
if (event.request.mode === 'navigate') {
event.respondWith(caches.match('/shell.html').then((shell) => shell ?? fetch(event.request)));
return;
}
event.respondWith(caches.match(event.request).then((hit) => hit ?? fetch(event.request)));
});

event.request.mode === 'navigate' matches navigation requests. The handler answers those requests within the service worker’s scope with the cached shell when it is available.

Registering with a fallback when there is no service worker

Section titled “Registering with a fallback when there is no service worker”

The page registers the worker when the API exists. When it does not, the example selects its network fallback marker and returns without registering a worker. Chrome’s app shell guide says unsupported browsers should receive a fallback experience and presents basic server-rendered static content as one of many options.

async function enableShell() {
if (!('serviceWorker' in navigator)) {
document.documentElement.dataset.shell = 'network';
return;
}
try {
await navigator.serviceWorker.register('/sw.js');
document.documentElement.dataset.shell = 'service-worker';
} catch (error) {
document.documentElement.dataset.shell = 'network';
console.warn('No shell cache:', error);
}
}
enableShell();

The data-shell attribute lets CSS or analytics distinguish the two modes without any other code change.

Specifications

SpecificationStatus
Service WorkersW3C draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes40highsource—
Chrome (Android)#Yes40highsource1
Edge (Desktop)#Yes17highsource—
Firefox (Desktop)#Yes44highsource—
Firefox (Android)#Yes44highsource2
Safari (macOS)#Yes11.1highsource—
Safari (iOS)#Yes11.3highsource3
Samsung Internet#Yes4.0highsource4
WebView (Android)#Yes40highsource5
  1. Derived by browser-compat-data mirroring from Chrome.
  2. Derived by browser-compat-data mirroring from Firefox.
  3. Derived by browser-compat-data mirroring from Safari.
  4. Derived by browser-compat-data mirroring from Chrome Android.
  5. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/service-worker.json · Global usage: 96 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-20 · Confidence: high (computed from sources)