AppCache is going away: what you need to do now

Chrome 85 removes support for AppCache by default. Most developers should migrate off AppCache now, rather than waiting any longer. Service workers — widely supported in current browsers — offer the alternative for providing the offline experience AppCache had offered.

Recent changes to the Chrome release schedule mean that the timing of some milestones may vary. A "deprecated" feature still exists but logs warning messages discouraging use. A "removed" feature no longer exists in the browser.

Deprecation in non-secure contexts Chrome 50 (April 2016)
Removal from non-secure contexts Chrome 70 (October 2018)
Deprecation in secure contexts Chrome 79 (December 2019)
AppCache scope restriction Chrome 80 (February 2020)
"Reverse" origin trial begins Chrome 84 (July 2020)
Removal from secure contexts, except for those opted-in to the origin trial Chrome 85 (August 2020)
Complete removal from secure contexts for everyone, with completion of origin trial October 5th, 2021 (roughly Chrome 95)

The reverse origin trial

Developers needing additional time can sign up for a "reverse" origin trial to extend AppCache availability. The trial starts in Chrome 84 (before the default removal in Chrome 85) and stays active through October 5th, 2021 (roughly Chrome 95). At that point, AppCache gets fully removed for everyone, even trial participants.

To participate:

  1. Request a token for your origin.
  2. Add the token to your HTML pages, using either:
    • An origin-trial <meta> tag in the head of each page, for example: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
    • An Origin-Trial HTTP header returned by your server, such as: Origin-Trial: TOKEN_GOES_HERE
  3. Add the same token to each AppCache manifest via a new manifest field:
ORIGIN-TRIAL:
TOKEN_GOES_HERE

There needs to be a new line between ORIGIN-TRIAL and your token.

Why tokens are needed in multiple places

The same origin trial token needs to be associated with all of your HTML pages that use AppCache, and with all of your AppCache manifests via the ORIGIN-TRIAL manifest field. This is unlike typical origin trials, where adding a token to your HTML pages is sufficient. This AppCache trial is special: you need token association with each manifest as well.

Adding the token to HTML pages enables the window.applicationCache interface in your web app. Pages without a token cannot use window.applicationCache methods and events, and cannot load resources from the AppCache — starting with Chrome 85, they behave as if AppCache did not exist. Adding the token to manifests signals that each manifest is valid; from Chrome 85, any manifest without an ORIGIN-TRIAL field is treated as malformed and its rules ignored.

Trial deployment timing

Although the "reverse" origin trial officially starts with Chrome 84, you can sign up today and add tokens to your HTML and AppCache manifests now. As your audience gradually upgrades to Chrome 84, the tokens you've added go into effect.

After adding a token to your AppCache manifest, check about://appcache-internals to verify that your local Chrome (version 84 or later) has properly associated the token with the manifest's cached entries. If recognized, you'll see a Token Expires: Tue Apr 06 2021... field associated with your manifest:

about://appcache-internals interface showing a recognized token.

Testing removal

Migrate off AppCache as soon as feasible. To test removal on your web apps, simulate it with the about://flags/#app-cache flag, available starting with Chrome 84.

Migration strategies

Service workers are painless to adopt with libraries like Workbox for complex cases. A polyfill based on service workers can replicate some AppCache functionality, but it does not provide a replacement for the window.applicationCache interface or the related AppCache events.

Be aware: Chrome disables AppCache functionality on any page loaded under the control of a service worker. Once a service worker controls a page, you can't use AppCache on that page anymore.

Because of this, avoid migrating piece-by-piece. Deploying a service worker with only part of your caching logic leaves you no fallback to AppCache. If you need to roll back after deploying a service worker, unregister it — as long as a registered service worker is in scope for a page, AppCache won't be used.

Browser support landscape

Firefox deprecated AppCache in release 44 (September 2015) and has removed support in its Beta and Nightly builds since September 2019. Safari deprecated AppCache in early 2018.

Chrome on iOS is a special case: it uses WKWebView rather than Chrome's engine. Service workers are not currently supported in iOS apps using WKWebView. Chrome's AppCache removal announcement does not cover availability of AppCache on Chrome for iOS, so keep this in mind if your app has a significant Chrome for iOS audience.

Some Android applications use Chrome WebView to display web content. Origin trials cannot be enabled for a WebView, so Chrome WebView will support AppCache without an origin trial until final removal, expected in Chrome 90.

Help and resources

For issues with a specific tool, open an issue in its GitHub repository. For general questions about migrating off AppCache, use Stack Overflow with the html5-appcache tag. For bugs related to Chrome's AppCache removal, report them via the Chromium issue tracker.

Relevant resources include an introduction to service workers (Workbox's overview), the service worker lifecycle, Progressive Web Apps training, and network reliability content. Useful tools are the AppCache polyfill, Workbox, and PWA Builder.