grunt-sri
Version:
Client-side caching & SRI generation for Grunt
148 lines (108 loc) • 3.94 kB
Markdown
# grunt-sri
[](https://travis-ci.org/neftaly/grunt-sri)
[](https://david-dm.org/neftaly/grunt-sri)
[](https://david-dm.org/neftaly/grunt-sri#info=devDependencies)
This tool generates a JSON manifest of file hashes & [sub-resource integrity](https://srihash.org/) data.
## Install
```shell
npm install --save-dev grunt-sri
```
## Usage
Add the following to your `Gruntfile.js`:
```js
module.exports = function (grunt) {
"use strict";
grunt.loadNpmTasks("grunt-sri");
grunt.initConfig({
"sri": {
// Use the default settings for *everything* in ./public/css
"bobsDefaultTask": {
"src": [
"public/**/*.css"
]
},
// Create a second manifest with custom settings
"janesCustomTask": {
"options": {
"algorithms": ["sha256"],
"dest": "./public/sri-directives.json",
"targetProp": "payload"
},
"files": [
{
src: "public/css/example.css",
type: "text/css",
id: "cssfile1"
},
{
src: "public/css/other.css"
}
]
}
}
});
grunt.registerTask("default", ["sri"]);
};
```
Run the command `grunt`. The manifest file will be created.
## Options
* String **dest**: Target JSON file.
Default `"./payload.json"`
* Boolean **merge**: Merge results with existing JSON file.
Default `false` (overwrite)
* Array **algorithms**: List of desired hash algorithms.
Default `["sha256", "sha512"]`
* String **targetProp**: Target JS object property name.
Default `null`
* Boolean **pretty**: Stringify the JSON output in a pretty format.
Default `false`
## Manifest
Metadata is stored in JSON format.
* The default manifest dest is `./payload.json`.
* File paths are relative to the CWD of Grunt.
This should be the project root.
* File identifiers are prefixed with the "@" symbol.
If no ID is specified, the path will be used.
Example:
```json
{
"@cssfile1": {
"path": "public/css/example.css",
"type": "text/css",
"integrity": "type:text/css sha256-XXXX sha512-XXXXXXXX",
"hashes": {
"sha256": "XXXX",
"sha512": "XXXXXXXX"
}
}
}
```
### Implementation
Data from the manifest can be loaded into markup.
Use the `integrity` property for SRI integrity attributes, a hash from `hashes` as a URL parameter for client-side caching, etc.
#### PHP
```php
// In production, consider compiling JSON to PHP assoc arrays
$payload = json_decode(file_get_contents("./payload.json"), true);
$sri = function (id) {
return $payload["payload"][id];
}
$element = "<link
href='/style.css?cache={ sri("@cssfile1")["hashes"]["sha256"] }'
integrity='{ $sri("@cssfile1")["integrity"] }'
rel='stylesheet'>";
```
#### JavaScript
**Note:** Node apps should use [subresource](https://github.com/neftaly/npm-subresource) or [handlebars-helper-sri](https://github.com/neftaly/handlebars-helper-sri), which don't require a build step.
```js
// ES6
var payload = require("./payload.json");
var sri = (id) => payload.payload[id];
var element = `<link
href='/style.css?cache=${ sri("@cssfile1").hashes.sha256 }'
integrity='${ sri("@cssfile1").integrity }'
rel='stylesheet'>`;
```
## SemVer
This tool follows SemVer from v0.1.0, as [SRI is now a W3C recommendation](https://www.w3.org/TR/SRI/).
Changes to the V1 SRI spec will be tracked with minor releases.