node package manager

grunt-appcache

Grunt task for generating an HTML5 AppCache manifest.

grunt-appcache

Grunt task for generating an HTML5 AppCache manifest from the specified list of files.

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-appcache --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-appcache');

In your project's Gruntfile, add a section named appcache to the data object passed into grunt.initConfig().

grunt.initConfig({
  appcache: {
    options: {
      // Task-specific options go here. 
    },
    your_target: {
      // Target-specific file lists and/or options go here. 
    },
  },
})

Type: String Default value: process.cwd()

The absolute or relative path to the directory to consider as the root of the application for which to generate the cache manifest.

Type: Boolean Default value: true

Specifies if to ignore the cache manifest itself from the list of files to insert in the "CACHE:" section.

Type: Boolean Default value: false

Specifies whether to write the "prefer-online" entry in the "SETTINGS:" section or not. More information.

String indicating the output path for the AppCache manifest. Mandatory.

Type: String Default value: undefined

The base URL to prepend to all expanded cache entries. In case of a Bower module, you can set this to /bower_components/mywebcomponent.

Type: Grunt globbing pattern Default value: undefined globbing pattern spec

The purposes is to merge all manifest files that match the globbing pattern into this generated manifest appcache. The contents of each matching files' sections are merged together, and subsequently added to the final cache, network and fallback target fields. It is very useful when you create you own Bower component with this Grunt Task or when you use a third party component that include their appcache manifest. See Bower usage examples below.

A descriptor for the "CACHE:" entries. A cache descriptor can be either :

Type: Grunt globbing pattern Default value: [] globbing pattern spec

Alternatively, this argument can be an Object.

Type: Object Default Value: { patterns: [], literals: [], pageslinks: []}

  • Containing the optional properties patterns (a cache descriptor, as defined earlier).

  • literals : String or Array of Strings to insert as is in the "CACHE:" section.

  • pageslinks a Grunt globbing pattern to defined all the pages to parse to extract href attribute of any kind of link tags and to extract src attribut of any script tag. This extraction will be added in the cache section.

Files to be ignored and excluded from the "CACHE:" entries. This parameter has been deprecated since v0.1.4, when proper support for the ! prefix to the glob patterns was added (this serves the same purpose while being more concise).

String or Array of Strings to insert as is in the "NETWORK:" section.

String or Array of Strings to insert as is in the "FALLBACK:" section.

In this example, the module is set to generate an AppCache manifest from the contents of the static directory, placing the resulting manifest in static/manifest.appcache. The basePath option allows the module to generate paths relative to the static directory, instead of the directory where the gruntfile resides.

grunt.initConfig({
  appcache: {
    options: {
      basePath: 'static'
    },
    all: {
      dest: 'static/manifest.appcache',
      cache: 'static/**/*',
      network: '*',
      fallback: '/ /offline.html'
    }
  }
})

The next example uses the extended syntax to the cache parameter:

grunt.initConfig({
  appcache: {
    options: {
      basePath: 'static'
    },
    all: {
      dest: 'static/manifest.appcache',
      cache: {
        patterns: [
          'static/**/*',         // all the resources in 'static/' 
          '!static/ignored/**/*' // except the 'static/ignored/' subtree 
        ],
        literals: '/'            // insert '/' as is in the "CACHE:" section 
      }
    }
  }
})

Real web applications are made by lots of pieces, which you can conveniently handle with Bower. Here you can find some examples to make so that grunt-appcache generates an AppCache manifest even when your application is split into Bower components.

grunt.initConfig({
  appcache: {
    options: {
        // appcache is always for the distrib version not for development 
        basePath: 'dist', 
    },
    // this target is only for components 
    mod: {
        // it will go to bower_components from the point of view the web app 
        baseUrl: '/bower_components/<%= package.name %>',
        // generate a partial appcache into the distrib folder 
        dest: 'dist/manifest.appcache',
        cache: {
            patterns: [
                // add all css, js and assets of my components 
                'dist/**/*',
                // but not informational files 
                '!dist/bower.json',
                '!dist/CHANGELOG.md',
                '!dist/README.md'
            ],
        },
        network: '*'
        // here you can add also fallback directives specific to it 
    },
    // this target is only for application 
    app: {
        // we are now in the root of the web app 
        baseUrl: '/',
        // appcache is always for the distrib version not for development 
        dest: 'dist/manifest.appcache',
        // parse all partials manifest files into bower_components 
        includes: 'dist/bower_components/**/*.appcache',
        cache: {
            patterns: [
                // add all css, js and assets of my application 
                'dist/**/*',
                // but not files from third party components 
                '!dist/bower_components/**',
                // and not informational files 
                '!dist/bower.json',
                '!dist/CHANGELOG.md',
                '!dist/README.md'
            ],
            // don't forget to cache the root 
            literals: '/',
            // and finish to add components which haven't a partial appcache 
            pageslinks: 'dist/index.html'
        },
        network: '*',
        fallback: '/ /offline.html'
    }
  }
})

To generate a partial appcache manifest, launch grunt appcache:mod. It will generate :

CACHE MANIFEST
# rev 1 - 2014-12-09T10:20:50.833Z
 
CACHE:
/bower_components/mymodule/images/checkerboard.png
/bower_components/mymodule/mymodule.css
/bower_components/mymodule/mymodule.js
 
NETWORK:
*

To generate a full appcache manifest, launch grunt appcache:app. It will generate :

CACHE MANIFEST
# rev 1 - 2014-12-10T07:27:17.969Z
 
CACHE:
/bower_components/mymodule/images/checkerboard.png
/bower_components/mymodule/mymodule.css
/bower_components/mymodule/mymodule.js
/images/icons/favicon.png
/bower_components/angular/angular-csp.css
/styles/myapp.css
/bower_components/jquery/jquery.js
/bower_components/angular/angular.js
/scripts/myapp.js
/
/images/myapplogo.png
/index.html
/robots.txt
 
NETWORK:
*
 
FALLBACK:
/ /offline.html