Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



29 Commits

Repository files navigation

Roots Image Pipeline

Join the chat at

Roots image pipeline is an asset pipeline for images which optionally compresses using imagemin and/or generates multiple sizes for use in HTML <picture> elements.

Note: This project is in early development, and versioning is a little different. Read this for more details.


  • make sure you are in your roots project directory

  • npm install roots-image-pipeline --save

  • modify your file to include the extension, for example:

    image_pipeline = require('roots-image-pipeline')
    module.exports =
      extensions: [image_pipeline(files: "assets/img/**", out: 'img', compress: true)]

Usage in templates

The function image() is exposed to your roots views, allowing you to output images quickly and easily. At it's simplest, simply pass image() a path to an image relative to the output directory specified in the function.

//- views/simple-example.jade
  != image('example/image.png')

  //- <img src="/img/example/image.png">

image() takes a number of options which determine how the image is resized and displayed.


Passing an array of sizes, containing a media query as well as width and/or height will generate the different sized images at compile time, and render the correct path for each source in your template.

//- views/picture-example.jade
  != image('example/image.png', {sizes: [{media: '(min-width: 40em)', width: 1024}, {width: 700}, {media: 'fallback', width: 1024}]})

  //- <picture>
  //-   <source srcset="/img/example/image-1024w.png" media="(min-width: 40em)">
  //-   <source srcset="/img/example/image-700w.png">
  //-   <img src="/img/example/image-1024w.png">
  //- </picture>
@2X Images

Passing retina: true in the options object will also generate and add the sources for @2x assets.

//- views/picture-example.jade
  != image('example/image.png', {sizes: [{media: '(min-width: 40em)', width: 1024}, {width: 700}, {media: 'fallback', width: 1024}], retina: true})

  //- <picture>
  //-   <source srcset="/img/example/image-1024w.png 1x, /img/example/image-1024w-@2X.png 2x" media="(min-width: 40em)">
  //-   <source srcset="/img/example/image-700w.png 1x, /img/example/image-700w-@2X.png 2x">
  //-   <img src="/img/example/image-1024w.png">
  //- </picture>



String or array of strings (minimatch supported) pointing to one or more file paths to be built. Default is assets/img/**


A path, relative to the roots project's root, to a manifest file (explained above), which contains a list of strings (minimatch supported) pointing to one more more file paths to be built.


If provided, all image files will be output to this directory in your project's output. Default is img


Compresses images. Default is true.


Options to be passed into imagemin plugins. Only does anything useful when compress is true.

# Defaults
    progressive: true
    max: 70
    quality: '50-70'
    speed: 1
    interlaced: true
  svgo: {}
    quality: 70
    alphaQuality: 50
    lossless: false

When true, after an image is passed through the compressor, a new .webp image is created in the output directory, alongside the matching jpg/png. Default is false.

Caveat: Converting some large png images with high levels of transparency can occasionally leave you with a webp image far larger than the original png. Use with caution.

To conditionally serve webp images to those browsers who can display them, add the following to your nginx configuration:

http {

  map $http_accept $webp_suffix {
    default "";
    "~*webp" ".webp";


server {

  # Load webp images instead of jpg/png if browser headers indicate support and files exist
  location ~* ^(?P<basename>.+)\.(jpg|jpeg|png)$ {
    try_files $basename$webp_suffix $uri =404;


Any option accepted by the various imagemin plugins can be passed through here.

License & Contributing