About

PostCSS processor to add links to WebP images for browsers that support it.

WebP is image format that is smaller, that PNG or JPEG, but it is supported only by Chrome.

Plugins for intergation with popular frontend build systems

• grunt-webpcss
• gulp-webpcss

Install

This plugin use cwebp for processing images. If you want to use this functionality read Installation Guide

Support

Postcss drop support node 0.10.0 by default. But if your need this version
use Promise polyfill.

 var Promise = require("es6-promise");
Promise.polyfill();

Versions >= 0.12 including 4.0.0 and iojs works without polyfills

Examples

Using with webpack and postcss-loader:
https://github.com/lexich/example-webpack-postcss-loader-webpcss

Using with gulp-postcss:

 var gulp = require('gulp');
var webp = require('gulp-webp');
var postcss = require('gulp-postcss');
var autoprefixer = require('autoprefixer-core');
var webpcss = require('webpcss');

gulp.task('webp', function () {
    return gulp.src('./images/*.{png,jpg,jpeg}')
        .pipe(webp())
        .pipe(gulp.dest('./images'));
});

gulp.task('css', function () {
    var processors = [
        autoprefixer,
        webpcss.default
    ];
    return gulp.src('./src/*.css')
        .pipe( postcss(processors) )
        .pipe( gulp.dest('./dist') );
});
gulp.task('default',['webp', 'css']);

Results of webpcss processor.

 /* Source */
.icon { color: #222; background-image: url('../images/icon.png'); }

/* Result */
.icon { background-image: url('../images/icon.png'); }
.icon { color: #222; }
.webp .icon { background-image: url('../images/icon.webp'); }

Results of webp task.
webp task appends .webp images for every .png image.

 #Source
> ls images
icon.png

#Result
> ls images
icon.png icon.webp

Options

• webpClass
  Type: String
  Default: '.webp'
  Class which prepend selector. For expample:
  before

 .test { background-image:url('test.png'); }

after

 .test { background-image:url('test.png'); }
.webp .test { background-image:url('test.webp'); }

.webp class indicate webp browser support. Recommends to use Modernizr

• noWebpClass
  Type: String
  Default: ""
  Class which prepend selector without webp content. For expample:
  noWebpClass=".no-webp"
  before

 .test { background-image:url('test.png'); }

after

 .no-webp .test { background-image:url('test.png'); }
.webp .test { background-image:url('test.webp'); }

• replace_from
  Type: RegExp
  Default: /.(png|jpg|jpeg)/
  RegExp pattern for replace

• replace_to
  Type: String or Function
  Default: .webp
  The contents of replace_from will be replaced by replace_to. They will be replaced with ".webp" by default.

  If replace_to is a Function, not replace_from but the whole url will be replaced with the return value of the function.

  The function will have a argument object, which has the following properties:

  url: The whole original url.

To checks browser support of webp format need to use Modernizr which adds .webp class to body if browser support WebP and browser will download smaller WebP image instead of bigger PNG.

 <script>
  document.documentElement.classname += (Modernizr.webp ? "webp" : "no-webp");
</script>

• process_selector
  Type: function(selector, baseClass)
  modify selector with baseClass

• inline
  Type: Boolean
  Default: false
  Turn on inline images mode. You need setup image_path and css_path for
  correct resolving image path.

 .test { background-image:url('test.png'); } // `${inline}/`test.png

after

 .test { background-image:url('test.png'); } // `${inline}/`test.png
.webp .test { background-image: url(data:image/webp;base64,UklGRmAAAABXRUJQVlA4IFQAAADwAQCdASoKAAgAAgA0JQBOgB6XKgsI3ogA/gEAtARF3E8iPiuncdF4zSgVjkZEgIatdknUme0fy3LBWFwbOjWUoaOOso78HmdNsa5gir1gmEwgAAA=); }

• image_root
  Type: String
  Default: ""
  This property needs to resolve absolute paths url(/images/1.png) while inlining images or other file info options.

• css_root
  Type: String
  Default: ""
  This property needs to resolve relative paths url(../images/1.png) url(image.png) while inlining images or other file info options.

• minAddClassFileSize
  Type: Number
  Default: 0
  webpClass will be added when images only of which greater than certain certain file size in bytes. It only works when the file path can be resolved(Either image_root or css_root or resolveUrlRelativeToFile) if they are files but not base64 encoded content.

• resolveUrlRelativeToFile
  Type: Boolean
  Default: false
  This property is needed to resolve relative paths url(../images/1.png) url(image.png) while inlining images or other options which are relative to file info . It will try to find resource file relative to current css file when it's true and css_root is not set.

• localImgFileLocator
  Type: Function
  Default: null
  When this property is set, it will be used to resolve the file path of image from the css url value while inlining images or other options which are relative to file info. In addition, resolveUrlRelativeToFile, css_root, image_root will be ignored.
  This function should return the exact file path in the file system and it has an argument object, which contains the following properties:

 {
  url, // The original url in the css value
  cssFilePath, // The absolute file path of the css file
}

• copyBackgroundSize
  Type: Boolean
  Default: false
  It will copy the background-size rule of same scope into the webp class rules if it's true

• replaceRemoteImage
  Type: Boolean
  Default: true
  It will add webp class when the url it's with host(eg. url(//foo.com/image.png) or url(http://foo.com/image.png) or url(https://foo.com/image.png)) if it's true

• cwebp_configurator
  Type: function(encoder){}
  Default: null
  You can configure cwebp encoder according cwebp documentation

Changelog

• 1.3.0 - Add option localImgFileLocator
• 1.2.1 - Add options copyBackgroundSize, replaceRemoteImage, bug fixes for absolute URL detection and unsupported based64 encoded content.
• 1.2.0 - Improve cross platform compatibility, add Function type as replace_to option, add options minAddClassFileSize, resolveUrlRelativeToFile
• 1.1.0 - add webpClass, noWebpClass options deprecate baseClass option
• 1.0.0 - add suport CWeb for automatic inline images in webp format
• 0.0.11 - add support of border-image, update deps
• 0.0.10 - update deps
• 0.0.9 - update postcss to 2.2.6
• 0.0.8 - fix bug with using @media-queryes and @support statement
• 0.0.7 - fix bug with multiple selectors
• 0.0.6 - add process_selector options for transform selectors
• 0.0.5 - update api according postcss convention