Concept in Performance
The app shell model
Published Updated
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.
How it works
Section titled “How it works”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.
Versioning and cleanup
Section titled “Versioning and cleanup”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.
Trade-offs
Section titled “Trade-offs”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.
Support position
Section titled “Support position”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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- The App Shell Model (developer.chrome.com)
- Offline and background operation (developer.mozilla.org)
- Precaching strategies
- Navigation preload and service worker boot time
- Caching strategies
- Offline fallback
Specifications
| Specification | Status |
|---|---|
| Service Workers | W3C draft |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 40 | high | source | — |
| Chrome (Android)# | Yes | 40 | high | source | 1 |
| Edge (Desktop)# | Yes | 17 | high | source | — |
| Firefox (Desktop)# | Yes | 44 | high | source | — |
| Firefox (Android)# | Yes | 44 | high | source | 2 |
| Safari (macOS)# | Yes | 11.1 | high | source | — |
| Safari (iOS)# | Yes | 11.3 | high | source | 3 |
| Samsung Internet# | Yes | 4.0 | high | source | 4 |
| WebView (Android)# | Yes | 40 | high | source | 5 |
- Derived by browser-compat-data mirroring from Chrome.
- Derived by browser-compat-data mirroring from Firefox.
- Derived by browser-compat-data mirroring from Safari.
- Derived by browser-compat-data mirroring from Chrome Android.
- Derived by browser-compat-data mirroring from Chrome Android.