Deprecated
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Using this application cache feature is highly discouraged; it’s in the process of being removed from the Web platform. As of Firefox 44+, when AppCache is used to provide offline support for a page, a warning message displays in the console advising developers to use Service workers instead (bug 1204581).
HTML5 provides an application caching mechanism that lets web applications run offline. This Application Cache (AppCache) interface lists resources that browsers should cache to be available offline. Applications that are cached load and work correctly offline, even if users press the Refresh button.
An application cache gives the following benefits:
To enable the application cache for an application, include the manifest
attribute in the <html>
element:
<html manifest="/example.appcache"> … </html>
The manifest
attribute references a URL for a cache manifest file: a text file that lists URLs that browsers should cache for your application.
You should include the manifest
attribute on each page of your site that you want cached. The browser does not cache pages without the manifest
attribute, unless such pages are listed in the manifest file. You do not need to list all pages you want cached in the manifest file, the browser implicitly adds every page that the user visits and that has the manifest
attribute set to the application cache.
Some browsers (e.g., Firefox) display a notification bar the first time a user loads an application that uses the application cache. The notification bar displays a message such as:
This website (example.com
) is asking to store data on your computer for offline use. [Allow] [Never for This Site] [Not Now]
The term "offline(-enabled) applications" sometimes refers specifically to applications that the user has allowed to use offline capabilities.
The use of an application cache modifies the normal process of loading a document:
The process for loading documents and updating the application cache is specified in greater detail below:
manifest
attribute, if no application cache exists, the browser loads the document and then fetches all the entries listed in the manifest file, creating the first version of the application cache.checking
event to the window.applicationCache
object, and fetches the manifest file, following the appropriate HTTP caching rules.noupdate
event to the applicationCache
object, and the update process is complete. Note that if you change any cached resources on the server, you must also change the manifest file itself, so that the browser knows it needs to fetch all the resources again.applicationCache.add()
—are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into this temporary cache, the browser sends a progress
event to the applicationCache
object. If any errors occur, the browser sends an error
event, and the update halts.cached
event is sent to the applicationCache
object. Since the document has already been loaded into the browser from the cache, the updated document will not be rendered until the document is reloaded (either manually or programatically).In Chrome you can clear the offline cache by selecting "Clear browsing data..." in the preferences or by visiting chrome://appcache-internals/. Safari has a similar "Empty cache" setting in its preferences but a browser restart may also be required.
In Firefox, the offline cache data is stored separately from the Firefox profile—next to the regular disk cache:
C:\Users\<username>\AppData\Local\Mozilla\Firefox\Profiles\<salt>.<profile name>\OfflineCache
/Users/<username>/Library/Caches/Firefox/Profiles/<salt>.<profile name>/OfflineCache
In Firefox the current status of the offline cache can be inspected on the about:cache
page (under the "Offline cache device" heading). The offline cache can be cleared for each site separately using the "Remove..." button in Tools -> Options -> Advanced -> Network -> Offline data.
Prior to Firefox 11, neither Tools -> Clear Recent History nor Tools -> Options -> Advanced -> Network -> Offline data -> Clear Now cleared the offline cache. This has been fixed.
On Linux, you can find the setting at Edit > Preferences > Advanced > Network > Offline Web Content and User Data
See also clearing the DOM Storage data.
Application caches can also become obsolete. If an application's manifest file is removed from the server, the browser removes all application caches that use that manifest, and sends an "obsoleted" event to the applicationCache
object. This sets the application cache's state to OBSOLETE
.
The manifest
attribute in a web application can specify either the relative path of a cache manifest file or an absolute URL. (Absolute URLs must be from the same origin as the application). A cache manifest file can have any file extension, but it must be served with the MIME type text/cache-manifest
.
AddType text/cache-manifest .appcache
to a .htaccess file within either the root directory, or the same directory as the application.The cache manifest file is a simple text file that lists the resources the browser should cache for offline access. Resources are identified by URI. Entries listed in the cache manifest must have the same scheme, host, and port as the manifest.
The following is a simple cache manifest file, example.appcache
, for an imaginary web site at www.example.com.
CACHE MANIFEST # v1 - 2011-08-13 # This is a comment. http://www.example.com/index.html http://www.example.com/header.png http://www.example.com/blah/blah
A cache manifest file can include three sections (CACHE
, NETWORK
, and FALLBACK
, discussed below). In the example above, there is no section header, so all data lines are assumed to be in the explicit (CACHE
) section, meaning that the browser should cache all the listed resources in the application cache. Resources can be specified using either absolute or relative URLs (e.g., index.html
).
The "v1" comment in the example above is there for a good reason. Browsers only update an application cache when the manifest file changes, byte for byte. If you change a cached resource (for example, you update the header.png
image with new content), you must also change the content of the manifest file in order to let browsers know that they need to refresh the cache. You can make any change you want to the manifest file, but revising a version number is the recommended best practice.
CACHE
, NETWORK
, and FALLBACK
A manifest can have three distinct sections: CACHE
, NETWORK
, and FALLBACK
.
CACHE:
CACHE:
section header (or immediately after the CACHE MANIFEST
line) are explicitly cached after they're downloaded for the first time.NETWORK:
NETWORK:
section header in the cache manifest file are white-listed resources that require a connection to the server. All requests to such resources bypass the cache, even if the user is offline. The wildcard character *
can be used once. Most sites need *
.FALLBACK:
FALLBACK:
section specifies fallback pages the browser should use if a resource is inaccessible. Each entry in this section lists two URIs—the first is the resource, the second is the fallback. Both URIs must be relative and from the same origin as the manifest file. Wildcards may be used.The CACHE
, NETWORK
, and FALLBACK
sections can be listed in any order in a cache manifest file, and each section can appear more than once in a single manifest.
The following is a more complete cache manifest file for the imaginary web site at www.example.com:
CACHE MANIFEST # v1 2011-08-14 # This is another comment index.html cache.html style.css image1.png # Use from network if available NETWORK: network.html # Fallback content FALLBACK: . fallback.html
This example uses NETWORK
and FALLBACK
sections to specify that the network.html
page must always be retrieved from the network, and that the fallback.html
page should be served as a fallback resource (e.g., in case a connection to the server cannot be established).
Cache manifest files must be served with the text/cache-manifest
MIME type. All resources served using this MIME type must follow the syntax for an application cache manifest, as defined in this section.
Cache manifests are UTF-8 format text files, and may optionally include a BOM character. Newlines may be represented by line feed (U+000A
), carriage return (U+000D
), or carriage return and line feed both.
The first line of the cache manifest must consist of the string CACHE MANIFEST
(with a single U+0020
space between the two words), followed by zero or more space or tab characters. Any other text on the line is ignored.
The remainder of the cache manifest must be comprised of zero or more of the following lines:
#
character, followed by zero or more characters of comment text. Comments may only be used on their own lines (after the initial CACHE MANIFEST
line), and cannot be appended to other lines. This means that you cannot specify fragment identifiers.
Section header Description CACHE:
Switches to the explicit section of the cache manifest (this is the default section). NETWORK:
Switches to the online whitelist section of the cache manifest. FALLBACK:
Switches to the fallback section of the cache manifest.
:
) in the section name.CACHE:
) section, each line is a valid URI or IRI reference to a resource to cache (no wildcard characters are allowed in this sections). Whitespace is allowed before and after the URI or IRI on each line. In the Fallback section each line is a valid URI or IRI reference to a resource, followed by a fallback resource that is to be served up when a connection with the server cannot be made. In the network section, each line is a valid URI or IRI reference to a resource to fetch from the network (or the wildcard character *
can be used in this section). Cache manifest files can switch from section to section at will (each section header can be used more than once), and sections are allowed to be empty.
An application cache always includes at least one resource, identified by URI. All resources fit into one of the following categories:
manifest
attribute.Resource categories are described in greater detail below.
Master entries are any HTML files that include a manifest
attribute in their <html>
element. For example, let's say we have the HTML file http://www.example.com/entry.html, which looks like this:
<html manifest="example.appcache"> <h1>Application Cache Example</h1> </html>
If entry.html
is not listed in the example.appcache
cache manifest file, visiting the entry.html
page causes entry.html
to be added to the application cache as a master entry.
Explicit entries are resources that are explicitly listed in the CACHE
section of a cache manifest file.
The NETWORK
section of a cache manifest file specifies resources for which a web application requires online access. Network entries in an application cache are essentially an "online whitelist"—URIs specified in the NETWORK
section are loaded from the server instead of the cache. This lets the browser's security model protect the user from potential security breaches by limiting access to approved resources.
As an example, you can use network entries to load and execute scripts and other code from the server instead of the cache:
CACHE MANIFEST NETWORK: /api
The cache manifest section listed above ensures that requests to load resources contained in the http://www.example.com/api/
subtree always go to the network without attempting to access the cache.
manifest
attribute set in the html
element) from the manifest file would not have the same result, because master entries will be added—and subsequently served from—the application cache.Fallback entries are used when an attempt to load a resource fails. For example, let's say the cache manifest file http://www.example.com/example.appcache
includes the following content:
CACHE MANIFEST FALLBACK: example/bar/ example.html
Any request to http://www.example.com/example/bar/
or any of its subdirectories and their content cause the browser to issue a network request to attempt to load the requested resource. If the attempt fails, due to either a network failure or a server error of some kind, the browser loads the file example.html
instead.
Each application cache has a state, which indicates the current condition of the cache. Caches that share the same manifest URI share the same cache state, which can be one of the following:
UNCACHED
IDLE
CHECKING
DOWNLOADING
UPDATEREADY
updateready
event, which is fired instead of the cached
event when a new update has been downloaded but not yet activated using the swapCache()
method.OBSOLETE
You can programmatically test to see if an application has an updated cache manifest file, using JavaScript. Since a cache manifest file may have been updated before a script attaches event listeners to test for updates, scripts should always test window.applicationCache.status
.
function onUpdateReady() { console.log('found new version!'); } window.applicationCache.addEventListener('updateready', onUpdateReady); if(window.applicationCache.status === window.applicationCache.UPDATEREADY) { onUpdateReady(); }
To manually start testing for a new manifest file, you can use window.applicationCache.update()
.
other-cached-page.html?parameterName=value
). This will make the browser bypass the cache and attempt to get it from network. To link to cached resources that have parameters parsed in JavaScript use parameters in the hash part of the link, such as other-cached-page.html#whatever?parameterName=value
.window.applicationCache.swapCache()
, though resources that have already been loaded will not be affected. To make sure that resources are loaded from a new version of the application cache, refreshing the page is ideal.*.appcache
files to expire immediately. This avoids the risk of caching manifest files. For example, in Apache you can specify such a configuration as follows:ExpiresByType text/cache-manifest "access plus 0 seconds"
Desktop | ||||||
---|---|---|---|---|---|---|
manifest
|
4 | 12 | 3.5
|
10 | 10.6 | 4 |
Secure context required | 70 | ≤79 | 60 | ? | 57 | ? |
Mobile | ||||||
---|---|---|---|---|---|---|
manifest
|
4 | 18 | 4 | 11 | 3.2 | 1.0 |
Secure context required | 70 | 70 | 60 | 49 | ? | 10.0 |
© 2005–2020 Mozilla and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache