Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

The App Shell Architecture

Learn the app shell model for PWAs: cache the minimal UI frame once, load content separately, and give users an instant, app-like first paint.

Native apps open instantly because their interface is already on the device. Websites normally cannot do that: every visit asks the server for the page, the styles, the scripts, and only then paints something. The app shell model closes that gap. You split your app into a small, stable frame (the shell) and the changing content. The shell is cached by a service worker and appears immediately, while the content loads on top of it.

In this lesson you will learn what belongs in the shell, how it differs from server-rendered pages, and how to build a stand-in that loads a shell and fills it with content.

What is the shell?

The shell is the minimum HTML, CSS and JavaScript needed to draw the app's chrome: the header, navigation, empty content area and perhaps a loading skeleton. It is the same for every screen and changes rarely. The content is the data that varies: articles, messages, products.

HTML
<body>
  <header class="top-bar">Trail Notes</header>
  <nav>...</nav>
  <main id="content" aria-live="polite">
    <!-- JavaScript fills this from cache or network -->
  </main>
  <script src="/app.js"></script>
</body>

On the first visit the browser downloads the shell and the service worker caches it. On every later visit the shell comes from the cache in a few milliseconds, even offline. Then app.js fetches the content (from the network, IndexedDB or a cache) and renders it.

flowchart TD
  A["Open the app"] --> B["Shell from cache: instant paint"]
  B --> C["app.js requests content"]
  C --> D{"Network available?"}
  D -->|Yes| E["Fresh content, store a copy"]
  D -->|No| F["Saved copy or offline message"]
  E --> G["Render into the shell"]
  F --> G

The shell is cached and shown first. Content follows and may come from several places.

What belongs in the shell

Good candidates:

  • The HTML skeleton with header, footer and navigation.
  • The main CSS and the fonts you actually use above the fold.
  • The core JavaScript that renders views and handles routing.
  • A logo and app icons (small SVGs are ideal).
  • A loading skeleton or placeholder for the content area.

Keep out of the shell:

  • Page-specific data, long articles, product lists.
  • Large images and videos.
  • Code for rarely visited screens (lazy-load it).

A smaller shell loads faster and costs less to update. If the shell is 2 MB of JavaScript, you have rebuilt the slow website, just with a cache in front of it.

Single-page apps and multi-page apps

The shell idea is natural for single-page apps (SPAs): one HTML file, JavaScript swaps views. It also works for multi-page sites. In a multi-page PWA each page is its own HTML document, and the service worker caches the shared assets (CSS, JS, fonts) and often a generic page layout. Frameworks help here: many build tools generate the list of shell files for you (see the precaching lesson in chapter 4).

Approach First load Later loads Complexity
Normal server-rendered site Full page Full page, cache headers only Low
SPA without a service worker Shell + JS + data Same, relies on HTTP cache Medium
App shell with service worker Shell + JS + data Shell instantly, data fresh Medium
Server-rendered with cached assets Full page Page from network, assets cached Low to medium

None of these is always right. A content-heavy blog is often best served by server-rendered HTML with cached assets. A tool or dashboard benefits more from the shell approach.

Stand-in: shell first, content second

The service worker is not available in this sandbox, so the runnable example below imitates the sequence with timers: the shell "appears" immediately from a fake cache, and content arrives after a delay from a fake network, falling back to saved content when "offline".

JS Stand-in: shell first, content second

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the important property: the first log line appears at about 0 ms in both runs. The shell does not wait for the network.

A skeleton in HTML

Showing an empty white box while content loads feels broken. A skeleton screen (grey placeholder shapes) tells the user something is coming. Here is one you can run; it uses a CSS animation and swaps in the text after a moment.

A loading skeleton

Updating the shell

Because the shell is cached, users keep seeing the old one until your service worker updates the cache. That is why shell files are usually versioned: a new release gets a new cache name, the new service worker fills it, and the old cache is deleted. Chapter 3 explains the update flow and chapter 4 shows precaching with versions.

A cached shell can get stuck on an old version if you forget to update the service worker. Every change to a shell file must come with a change that makes the browser fetch a new service worker (a new version string or a build hash).

When not to use an app shell

If your pages are mostly text that changes often, such as news articles, caching an empty frame gains little. Instead, serve full HTML from the server and cache the assets, or use a network-first strategy for pages (see Network First). The shell model shines when the interface is the heavy part and the data is light.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main goal of the app shell model?

    The cached shell provides an instant first paint, and content is added afterwards.
  2. 2. Which item does NOT belong in the shell?

    Changing data belongs to the content layer, not to the stable shell.
  3. 3. Why should shell files be versioned?

    A new cache version lets the new service worker fill fresh files and delete the old ones.
  4. 4. For a news site with mostly article text, what is usually a better fit?

    Content-heavy pages gain little from a cached empty frame; real HTML plus cached assets is simpler.

Summary

  • The app shell is the small, stable UI frame cached by a service worker.
  • Content loads separately from the network or storage and is rendered inside the shell.
  • Keep the shell small; lazy-load rare screens and heavy media.
  • Use skeletons so loading feels intentional.
  • Version shell files so updates reach users.

Next: Your First PWA