Git Product home page Git Product logo

broccoli-rev's Introduction

broccoli-rev

A Broccoli plugin that adds the checksum of files to the output filename. This is useful in situations where you need unique names for asset files so you can bust HTTP caches.

Usage

broccoli-rev is actually two plugins in a single module.

The first plugin (called rev) maps every file in the input tree to a file with the same name + a hash of the file's contents. For example, a file named styles/fonts.css in the input tree might be named styles/fonts-83f26306.css in the output. This step also generates a manifest file in the output that contains a map of all the original file paths to their new versions.

var rev = require('broccoli-rev');

var revvedTree = rev(myTree, {

  // The revision number or string for this build, if all files should use
  // the same revision. If not given, the revision for a given file is the
  // MD5 checksum of its contents. Defaults to null.
  revision: null,

  // The length to use for the hash that is appended to the filename
  // immediately before the file extension when using the file's checksum
  // as its revision. Defaults to 8.
  hashLength: 8,

  // The name of a file in the destination directory that will be created
  // that contains a mapping of unrev'd filenames to their rev'd versions.
  // This is useful for doing search & replace in files that reference rev'd
  // files later on. Defaults to "/rev-manifest.json".
  manifestFile: '/rev-manifest.json'

});

The second plugin in this module is optional, but represents a common use case. Basically, it takes the manifest file from the first step and interpolates its values into a Handlebars template using a rev helper function.

For example, let's say you're generating an HTML page that includes a JavaScript file that you want to manage using broccoli-rev. Your index.hbs file might look like this:

<!DOCTYPE html>
<html>
  <head>
    <script src="{{ rev "built-scripts/navigation.js" }}"></script>
  </head>
  <body></body>
</html>

You might also have a scripts directory that contains source versions of all the scripts you want to run on your HTML page. In this scenario, you could use the following Brocfile.js to build rev'd versions of the scripts and interpolate the rev'd file names into the template for index.html.

var pickFiles = require('broccoli-static-compiler');
var mergeTrees = require('broccoli-merge-trees');
var rev = require('broccoli-rev');

var indexTree = pickFiles('templates', {
  srcDir: '/',
  destDir: '/',
  files: [ 'index.hbs' ]
});

// scriptsTree is a rev'd version of all files in the scripts
// source directory + the rev-manifest.json file.
var scriptsTree = rev(pickFiles('scripts', {
  srcDir: '/',
  destDir: '/built-scripts'
}));

var indexAndScriptsTree = mergeTrees([ indexTree, scriptsTree ]);

// Render index.hbs => index.html using a rev Handlebars helper
// function that looks up paths in the rev-manifest.json file.
module.exports = rev.rewriter(indexAndScriptsTree, {
  inputFile: 'index.hbs',
  outputFile: 'index.html'
});

License

MIT

broccoli-rev's People

Contributors

mjackson avatar rwjblue avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

broccoli-rev's Issues

Recommend a method for consuming the manifest file

The README should contain a recommended method for consuming the manifest file, like gulp-rev has, except that I'm not sure the best way to do it.

Currently, the rev-manifest.json file is added to the destDir when broccoli-rev runs. Ideally it would be easy to specify another tree with an HTML template, for example, that contains references to the revved files. Then we could show how to use a templating engine like Handlebars together with the manifest file to generate the appropriate paths to the revved files, and trash the manifest file afterwards.

In a task-based system this is fairly straightforward because we can make sure the task that generates the manifest runs before the one that needs to use it. However, being new to broccoli I'm still learning to structure code without explicit tasks.

@joliss Would you have any suggestions about the best way to do this? Thank you in advance! :)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.