gunta/grunt-manifest

Generates HTML5 Cache Manifest files

grunt-manifest

Generate HTML5 Cache Manifest files.

Getting Started

This plugin requires Grunt ~0.4.5

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-manifest --save-dev

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

grunt.loadNpmTasks('grunt-manifest');

HTML5 Cache Manifest task

Run this task with the grunt manifest command.

Visit the Appcache Facts for more information on Cache Manifest files.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Parameters

options

Type: Object
Default: {}

This controls how this task (and its helpers) operate and should contain key:value pairs, see options below.

src

Type: String Array
Default: undefined

Sets the input files.

dest

Type: String Default manifest.appcache

Sets the name of the Cache Manifest file. Remember that .appcache is now the W3C recommended file extension.

Options

basePath

Type: String Default: undefined

Sets the base path for input files. It's recommended to set this.

cache

Type: String Default: undefined

Adds manually a string to the CACHE section. Needed when you have cache buster for example.

process

Type: Function Default: undefined

A function to process src files path strings before adding them on the appcache manifest.

exclude

Type: String Array Default: undefined

Exclude specific files from the Cache Manifest file.

network

Type: String Array Default: "*" (By default, an online whitelist wildcard flag is added)

Adds a string to the NETWORK section.

See here for more information.

fallback

Type: String Array Default: undefined

Adds a string to the FALLBACK section.

See here for more information.

preferOnline

Type: Boolean Default: undefined

Adds a string to the SETTINGS section, specifically the cache mode flag of the prefer-online state.

See here for more information.

headcomment

Type: String
Default: undefined

Adds ability to append custom text to the top of the manifest file. For example, you can put your app version, so that the manifest only updates when your app version changes. Note: A '#' is added to the beginning of the text for you.

verbose

Type: Boolean Default: true

Adds a meta "copyright" comment.

timestamp

Type: Boolean Default: true

Adds a timestamp as a comment for easy versioning.

Note: timestamp will invalidate application cache whenever cache manifest is rebuilt, even if contents of files in src have not changed.

hash

Type: Boolean Default: false

Adds a sha256 hash of all src files (actual contents) as a comment.

This will ensure that application cache invalidates whenever actual file contents change (it's recommented to set timestamp to false when hash is used).

master

Type: String Array Default: undefined

Hashes master html files (used with hash). Paths must be relative to the 'basePath'. This is useful when there are multiple html pages using one cache manifest and you don't want to explicitly include those pages in the manifest.

Config Example

// Project configuration
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  manifest: {
    generate: {
      options: {
        basePath: '../',
        cache: ['js/app.js', 'css/style.css'],
        network: ['http://*', 'https://*'],
        fallback: ['/ /offline.html'],
        exclude: ['js/jquery.min.js'],
        preferOnline: true,
        headcomment: " <%= pkg.name %> v<%= pkg.version %>",
        verbose: true,
        timestamp: true,
        hash: true,
        master: ['index.html'],
        process: function(path) {
          return path.substring('build/'.length);
        }
      },
      src: [
      	'build/some_files/*.html',
    	  'build/js/*.min.js',
    	  'build/css/*.css'
      ],
      dest: 'manifest.appcache'
    }
  }
});

Output example

CACHE MANIFEST
# APPNAME v1.0.0
# This manifest was generated by grunt-manifest HTML5 Cache Manifest Generator
# Time: Mon Jan 01 2155 22:23:24 GMT+0900 (JST)

CACHE:
js/app.js
css/style
css/style.css
js/zepto.min.js
js/script.js
some_files/index.html
some_files/about.html

NETWORK:
*

# hash: 76f0ef591f999871e1dbdf6d5064d1276d80846feeef6b556f74ad87b44ca16a

You do need to be fully aware of standard browser caching. If the files in CACHE are in the network cache, they won't actually update, since the network cache will spit back the same file to the application cache. Therefore, it's recommended to add a hash to the filenames's, akin to rails or yeoman. See here why query strings are not recommended.

Release History

• 2015/01/26 - v0.4.1 - Documented process for renaming files.
• 2012/10/23 - v0.4.0 - Changed package and repository name to grunt-manifest.
• 2012/10/23 - v0.3.0 - Upgraded to Grunt 0.4. Fixed dependencies. Fixed basePath.
• 2012/10/23 - v0.2.1 - Added possibility to manually specify "CACHE:" files. Made comments optional.
• 2012/09/28 - v0.2.0 - Refactored from grunt-contrib into individual repo.

grunt-manifest's Issues

Do not use setBase()

gruntjs/grunt#492

Allow usage of globbing patterns in exclude option

Should be fairly easy to implement by using grunt.file.isMatch and it helps a lot when excluding folders or specific files.

// Exclude files
if (options.exclude) {
  files = files.filter(function (item) {
    return !grunt.file.isMatch(options.exclude, item);
  });
}

Can make a PR. If there is somebody out there who can merge it.

EPERM, operation not permitted

When I run the manifest task with this config

 manifest: {
            generate: {
                options: {
                    basePath: '/',
                    cache: ['/scripts/scripts.js', '/styles/main.css'],
                    network: ['*', 'http://*', 'https://*'],
                    fallback: ['/ /offline.html'], 
                    exclude: ['js/jquery.min.js'],
                    preferOnline: true,
                    verbose: true,
                    timestamp: true,
                    hash: true,
                    master: ['index.html']
                },
                src: [
                    '**/*.html',
                    '/scripts/**/*.js',
                    '/styles/**/*.css',
                    '*.{ico,png,txt}',
                    'assets/images/**/*',
                    'assets/fonts/**/*'
                ],
                dest: 'manifest.appcache'
            }
        }

It crashes.

Running "manifest:generate" (manifest) task
Warning: EPERM, operation not permitted 'C:\$Recycle.Bin\S-1-5-18' Use --force to continue.

Aborted due to warnings.

This happens on a Windows 8 x64 installation.

Setting the verbose comment

Only '# This manifest was generated by grunt-manifest HTML5 Cache Manifest Generator\n'. Why can't I set it?

support add prefix to files

Thanks for grunt-manifest, its super convenient :)

In case I did not put .appcache file in the root folder, for example:

I have a grunt config looks like

manifest: {
      generate: {
        options: {
          basePath: "../",
          preferOnline: false,
          verbose: true,
          timestamp: true
        },
        src: [
            "public/osx/*.html"
        ],
        dest: "public/osx/manifest.appcache"
      }
    } 

The generated appcache file looks like

CACHE MANIFEST
# This manifest was generated by grunt-manifest HTML5 Cache Manifest Generator
# Time: Thu Mar 14 2013 21:52:50 GMT+0800 (CST)

CACHE:
public/osx/index.html

the offline cache will try to fetch wrong public/osx/public/osx/index.html instead of correct /public/osx/index.html.

but what I really want is to have CACHE files with / as prefix.

/public/osx/index.html

instead of

public/osx/index.html

to prevent some miss reference issue.

broken file path

The appcache file generated has

scripts/fscharts/a
the folder fscharts has

angular-fusioncharts.min.js

It however once adds it correctly but after adding links for views in the file,
scripts/fscharts/a

has this line in code.

In browser , it results in

Application Cache Error event: Resource fetch failed (4) http://localhost:9000/scripts/fscharts/a

Produce a manifest for development and on for dist

I need to produce a manifest for development stage (with non-minified scripts, for example), with a 'dest' set to /app', instead of 'dist/', where I put it when building... How would you write manifest: {} block in Gruntfile.js to support these two scenarios?

Recurse into css files to find images

Like when there's:

#foo {
  background: url(/background.jpg);
  repeat: 'yes please';
}

I investigated and am certain only url( needs to be scanned for.

verbose option misleading

I think verbose option in its current form is misleading. I actually expected it to throw out more info on console during the manifest build process not to add a Copyright reference to the header of the manifest file.

I'd separate things a bit and push the behaviour of the current verbose option to a �richHeaders for instance or something along the lines. And then verbose could act as an actual �--verbose in the *nix world.

Since the features are both harmless and don't break anything, the switch would be possible without legacy support dance?

Possility to define external URLs

Sometimes, we want to add to the manifest file some external URLs (Fonts from Google Font, CDN, ...).

Is it possible to add to this plugin configuration object, some external URLs ? according to the code, it's not.

Manu

Add option to add "manifest" attribute on <html> tag

I guess the usual case is that the manifest file is supposed to be used in production only, not during the development. Is there a best practice to add the manifest attribute to the <html> tags as part of the build process?

Or maybe we should add an option for grunt-manifest directly?

Planning .0.4.x support?

I see that the wiki says that this plugin has plans to be included as part of the grunt-contrib series of plugins, which are all supposed to be 0.4.x compatible...yet this one doesn't appear to be there yet. Are plans in the works to make this work in the 4.0 environment? Looks like it needs to build in support for the changes regarding iterating over configuration targets. Also looks like you're already aware of this as I see the following comment in the source:

    // TODO: ditch this when grunt v0.4 is released
    this.files = this.files || helpers.normalizeMultiTaskFiles(this.data, this.target);

Sure hope so as this is a vital plugin for performance of web/mobile apps, IMO :)
Thx!

grunt-contrib-lib

FYI: we're changing the name of grunt-contrib-lib to grunt-lib-contrib. Please update your deps!

Fails with grunt rc6

Running the task with the latest grunt version gives my this error:

Warning: Cannot read property 'src' of undefined Use --force to continue.

Maybe related to gruntjs/grunt#606

grunt-contrib

Hey Gunther!

I'm one of the maintainers of grunt, and I have a quick favor to ask.

grunt-contrib-* plugins are curated by the grunt team and several community members @ gruntjs. Given that this plugin is not part of the official contrib series, we'd really appreciate it if you'd change the name so as not to confuse the community.

Thanks a ton!

No hash written to manifest file

There's no hash written to the manifest file on following configuration:

manifest: {
  dist: {
    options: {
      basePath: '<%= yeoman.dist %>/',
      cache: [],
//          network: ['*', 'http://*', 'https://*'],
      network: ['http://*'],
//          fallback: ['/ /offline.html'],
//          exclude: ['js/jquery.min.js'],
      preferOnline: false,
      timestamp: true,
      verbose: false,
      hash: true,
      master: ['index.html']
    },
    src: [
      'index.html',
      '{newcomer,expert}/*/*.html',
      'bower_components/*/*',
      'images/**/*',
      'scripts/*.js',
      'styles/*.css',
      '{videos,fonts}/*'
    ],
    dest: '<%= yeoman.dist %>/manifest.appcache'
  }
}

version: 0.4.0

can't add the extend string for list

for example
CACHE:
a.js
b.js
c.js

i want to add a string at last, like
CACHE:
a.js?v=12345
b.js?v=12345
c.js?v=12345

Exclude files based on pattern

I have a local copy of jquery as a fallback, for the one on cdn, I also add a checksum to each file based on its contents, so it end up like this:

jquery.min.d4a20d75.js

I would like to eclude it like this:

jquery.min.*.js

So I do not have to hard code in a value that can change

NPM Appcache Documentation Link Incorrect

I was checking out your NPM package for this project, and noticed the "Appcache Facts" link in the overview section links to http://appcachefacts.info/ which is apparently rendering a porn site. I'm guessing that's not what you intended as the link in this repo's README leads somewhere else.

https://www.npmjs.com/package/grunt-contrib-manifest

Really slow when using basePath

I've been using this plugin for a while, but it's been running terribly slow. Today I decided to investigate why, since adding about 800 files to a manifest shouldn't take more than a few seconds (instead it was actually taking a few minutes!)

The culprit seems to be this line of code in the plugin:

// check to see if src has been set
if (typeof file.src === "undefined") {
  grunt.fatal('Need to specify which files to include in the manifest.', 2);
}

For some reason calling typeof file.src actually causes the src array of paths to be expanded! Why? I have no idea. And since I was using basePath and my src array was full of paths that started with **/*.ext, expanding those src would essentially traverse my entire project and expand thousands of files.

Anyway, the workaround for now is to ditch basePath and use the process filter while changing src paths to include the original basePath.

So I went from:

manifest: {
  dist: {
    options: {
      basePath: 'dist/'
    },
    src: [
      '**/*.css',
      '**/*.jpg',
      '**/*.js',
      '**/*.png',
    ],
    dest: "dist/manifest.appcache"
  }
}

to

manifest: {
  dist: {
    options: {
      process: function(path) {
        // strip out the "dist/" prefix instead of relying on basePath to do it for us
        return path.substring('dist/'.length);
      }
    },
    src: [
      'dist/**/*.css',
      'dist/**/*.jpg',
      'dist/**/*.js',
      'dist/**/*.png',
    ],
    dest: "dist/manifest.appcache"
  }
}

Now it works fast!

exclude option to Support whole folder.

I would like to the ability to exclude a whole folder and not have to specific all files in a folder.

exclude: [ 'images/moblie-icons/' ],

what's the difference with options.cache list and src list?

and the other question is~
can i set a html list that can auto set propety in files.

update documention (README) to include the options.process

Looking at the source I noticed that there is a very useful option to set a process function to modify the cached files path before adding them on the appcache manifest, we should include this option in the documentation along with an usage example.

Update version NPM serves to reflect latest here

When installing grunt-manifest using npm the version that is pulled down looks to be a few versions behind what is in github - is there any chance of updating this?

Add URL encoding to the file path entries in manifest file

applicationCache doesn't work if the manifest file has a filename with space.
example: "my app.css"

Kindly add URL encoding of the filepath while making entry to manifest file.
example: "path/to/folder name/file name.ext" should output "path/to/folder%20name/file%20name.ext"

Add option to use content hash instead of timestamp

This way application cache fill be reloaded only if cached content changes (instead on every build).

Looking for new mantainers

Hi everyone!
It's official:

I found I couldn't find the time to maintain this repository anymore (also not using Grunt, nor Cache Manifest anymore),
so I'm looking for new maintainers.

Anyone ready up to the task,
wanting to commit to it in the long term?

A fallback value of "/ /offline.html" is encoded as "/%20/offline.html"

#59 should fix this

manifest contains folder names

I have updated a project from grunt 0.3.x to 0.4.1 and grunt-contrib-manifest from 0.2 to the current version 0.4.0.

Now my appcache manifest contains not only files but directory names too which the browser can't download of course.

The configuration is basically the same as it was before and looks like this:

manifest: {
            generate: {
                options: {
                    basePath: "<%=pkg.folders.build + pkg.name + '-' + pkg.version%>",
                    network: ["*"],
                    fallback: [],
                    exclude: [],
                    preferOnline: false,
                    timestamp: true
                },
                src: [
                    "**/*"

                ],
                dest: "<%= pkg.folders.build + pkg.name + '-' + pkg.version%>/hwa-mobile.manifest"
            }
        },

I have tried different src-Strings but I can't get it to work that automatically ALL of the files (and only files) are included. I could manually exclude the folders but I don't want to change the buildfile every time something changes in folder structure.

Any hints?

Thanks!
Marco

Not latest version committed to npmjs

Hey, I don't know if it is your responsibility but the latest version of this package on npmjs.com is 0.4.0.

Fallback encodeURI

Hi,
I have an issue with the "fallback" option.
You encode the given strings which leads to a "my-file.ab fb/my-file.ab" generated as "my-file.ab%20fb/my-file.ab".
And that doesn't work with the cache manifest.

I fixed it by simply removing the encodeURI(). But it only works because my paths are clean.

CACHE section empty if not specifying cache option

Here is my manifest task config:

manifest: {
  generate: {
    options: {
      basePath: "public/"
    },
    src: [
      "public/css/main.css",
      "public/css/fonts/**/*",
      "public/js/main.min.js",
      "public/js/vendor/zepto.min.js",
      "public/js/vendor/jquery.min.js",
      "public/img/**/*"
    ],
    dest: 'public/manifest.appcache'
  }
},

The expected output would be all the files specified in the src parameter (all the fonts inside public/css/fonts/ and all the images in public/img/ directories also). What I get is an empty CACHE section.
When I copied the src array to options.cache it outputted them in the CACHE section like this:

CACHE:
public/css/main.css
public/css/fonts/**/*
public/js/main.min.js
public/js/vendor/zepto.min.js
public/js/vendor/jquery.min.js
public/img/**/*

Clearly not parsing the directories and placing correct files.
Any clue about this?
Thanks.

Prepending slash

Is there a way to prepend a slash to all the file paths?

Currently:

app/file/path

I'd like it to be

/app/file/path

Wrong package description on npmjs.org

The package description on https://npmjs.org/package/grunt-contrib-manifest reads:

Precompile Underscore templates to JST file.

Grunt 0.4 Release

I'm posting this issue to let you know that we will be publishing Grunt 0.4 on Monday, February 18th.

If your plugin is not already Grunt 0.4 compatible, would you please consider updating it? For an overview of what's changed, please see our migration guide.

If you'd like to develop against the final version of Grunt before Monday, please specify "grunt": "0.4.0rc8" as a devDependency in your project. After Monday's release, you'll be able to use "grunt": "~0.4.0" to actually publish your plugin. If you depend on any plugins from the grunt-contrib series, please see our list of release candidates for compatible versions. All of these will be updated to final status when Grunt 0.4 is published.

Also, in an effort to reduce duplication of effort and fragmentation in the developer community, could you review the grunt-contrib series of plugins to see if any of your functionality overlaps significantly with them? Grunt-contrib is community maintained with 40+ contributors—we'd love to discuss any additions you'd like to make.

Finally, we're working on a new task format that doesn't depend on Grunt: it's called node-task. Once this is complete, there will be one more conversion, and then we'll never ask you to upgrade your plugins to support our changes again. Until that happens, thanks for bearing with us!

If you have any questions about how to proceed, please respond here, or join us in #grunt on irc.freenode.net.

Thanks, we really appreciate your work!