Preparing for AppCache removal

Chrome 85 removes support for AppCache by default. Most developers should migrate off AppCache now, and not wait any longer.

Jeff Posnick

Following up on previous announcements, support for AppCache will be removed from Chrome and other Chromium-based browsers. We encourage developers to migrate off of AppCache now, rather than waiting any longer.

Service workers, which are widely supported in current browsers, offer an alternative to providing the offline experience that AppCache had offered. See Migration strategies.

Timeline

Recent changes to the Chrome release schedule means that the timing of some of these steps may vary. We will attempt to keep this timeline up-to-date, but at this point, please migrate off of AppCache as soon as possible, instead of waiting for specific milestones.

A "deprecated" feature still exists, but logs warning messages discouraging use. A "removed" feature no longer exists in the browser.

Origin trial

The timeline lists two upcoming milestones for removal. Beginning with Chrome 85, AppCache will no longer be available in Chrome by default. Developers who require additional time to migrate off of AppCache can sign up for a "reverse" origin trial to extend the availability of AppCache for their web apps. The origin trial will start in Chrome 84 (in advance of the default removal in Chrome 85), and will be active through October 5th, 2021 (roughly Chrome 95). At that point, AppCache will be fully removed for everyone, even those who had signed up for the origin trial.

To participate in the "reverse" origin trial:

1. Request a token for your origin.
2. Add the token to your HTML pages. There are two ways to do that:
   • Add an origin-trial <meta> tag to the head of each page. For example: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
   • Alternatively, configure your server to return responses containing the Origin-Trial HTTP header. The resulting response header should look something like: Origin-Trial: TOKEN_GOES_HERE
3. Add the same token to your AppCache manifests. Do this via a new field in your manifest, with the format:

ORIGIN-TRIAL:
TOKEN_GOES_HERE

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

You can see a sample project embedded below that demonstrates adding the correct origin trial tokens into both the index.html and manifest.appcache files.

Why are tokens needed in multiple places?

The same origin trial token needs to be associated with:

• All of your HTML pages that use AppCache.
• All of your AppCache manifests via the ORIGIN-TRIAL manifest field.

If you've participated in origin trials in the past, you might have added the token just to your HTML pages. The AppCache "reverse" origin trial is special in that you need to associate a token with each of your AppCache manifests as well.

Adding the origin trial token to your HTML pages enables the window.applicationCache interface from within your web apps. Pages that are not associated with a token won't be able to use window.applicationCache methods and events. Pages without a token also won't be able to load resources from the AppCache. Starting with Chrome 85, they will behave as if AppCache did not exist.

Adding the origin trial token to your AppCache manifests indicates that each manifest is still valid. Starting with Chrome 85, any manifests that does not have an ORIGIN-TRIAL field will be treated as malformed, and the rules within the manifest will be ignored.

Origin trial deployment timing and logistics

While the "reverse" origin trial officially starts with Chrome 84, you can sign up for the origin trial today and add the tokens to your HTML and AppCache manifests. As your web app's audience gradually upgrades to Chrome 84, any tokens that you've already added will go into effect.

Once you've added a token to your AppCache manifest, visit about://appcache-internals to confirm that your local instance of Chrome (version 84 or later) has properly associated the origin trial token with your manifest's cached entries. If your origin trial is recognized, you should see a field with Token Expires: Tue Apr 06 2021... on that page, associated with your manifest:

Testing prior to removal

We strongly encourage you to migrate off of AppCache as soon as is feasible. If you want to test removal of AppCache on your web apps, use the about://flags/#app-cache flag to simulate its removal. This flag is available starting with Chrome 84.

Migration strategies

Service workers, which are widely supported in current browsers, offer an alternative to the offline experience provided by AppCache.

We've provided a polyfill that uses a service worker to replicate some of the functionality of AppCache, though it does not replicate the entire AppCache interface. In particular, it does not provide a replacement for the window.applicationCache interface or the related AppCache events.

For more complex cases, libraries like Workbox provide an easy way to create a modern service worker for your web app.

Service workers and AppCache are mutually exclusive

While working on your migration strategy, please keep in mind that Chrome will disable AppCache functionality on any page that's loaded under the control of a service worker. In other words, as soon as you deploy a service worker that controls a given page, you're no longer able to use AppCache on that page.

Because of this, we recommend that you do not attempt to migrate to service workers piece-by-piece. It would be a mistake to deploy a service worker that only contains some of your caching logic. You cannot fall back on AppCache to "fill in the gaps."

Similarly, if you deploy a service worker prior to AppCache removal, and then discover that you need to roll back to your previous AppCache implementation, you need to ensure that you unregister that service worker. As long as there's a registered service worker in scope for a given page, AppCache will not be used.

The cross-platform story

We encourage you to follow up with a specific browser vendor if you'd like more information about their plans for AppCache removal.

Firefox on all platforms

Firefox deprecated AppCache in release 44 (September 2015), and has removed support for it in its Beta and Nightly builds as of September 2019.

Safari on iOS and macOS

Safari deprecated AppCache in early 2018.

Chrome on iOS

Chrome for iOS is a special case, as it uses a different browser engine than Chrome on other platforms: the WKWebView. Service workers are not currently supported in iOS apps using WKWebView, and Chrome's AppCache removal announcement does not cover the availability of AppCache on Chrome for iOS. Please keep this in mind if you know that your web app has a significant Chrome for iOS audience.

Android WebViews

Some developers of Android applications use Chrome WebView to display web content, and might also use AppCache. However, it's not possible to enable an origin trial for a WebView. In light of that, Chrome WebView will support AppCache without an origin trial until the final removal takes place, expected in Chrome 90.

Learn more

Here are some resources for developers migrating from AppCache to service workers.

Articles

• Service Workers: an Introduction
• The Service Worker Lifecycle
• Progressive Web Apps Training
• Network Reliability

Tools

• AppCache Polyfill
• Workbox
• PWA Builder

Getting help

If you run into an issue using a specific tool, open an issue in its GitHub repository.

You can ask a general question about migrating off of AppCache on Stack Overflow, using the tag html5-appcache.

If you encounter a bug related to Chrome's AppCache removal, please report it using the Chromium issue tracker.

Hero image based on Smithsonian Institution Archives, Acc. 11-007, Box 020, Image No. MNH-4477.