grunt-css-url-embed

Embed URL's as base64 strings inside your stylesheets

grunt-css-url-embed

  

Embed URLs as base64 data URIs inside your stylesheets

There are lots of base64 embedding Grunt plugins out there, but pretty much all of them are already outdated and/or abandoned. This plugin aims to change that.

This plugin requires Grunt ~0.4.0 and Python 2.7, since it depends on node-gyp.

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-css-url-embed --save-dev

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

grunt.loadNpmTasks('grunt-css-url-embed');

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

Both image and font URLs are supported. Remote(http/https) URLs are supported as well.

Type: String

Default: . or the directory of Gruntfile.js

The base directory for URLs. Can be absolute or relative to the directory of your Gruntfile.js.

Type: Boolean

Default: true

Will the script terminate if the file referenced by the URL is missing or the request to get it failed?

When set to false a warning will be produced for each missing file or failed request.

Type: String

Default: No restrictions

Skip URLs that are larger than the specified value.

For example: '5 MB', '30 KB', '300 B'.

Type: Boolean

Default: false

Specifies the mode of embedding.

  • true (inclusive) means that you have to manually mark each URL that needs to be embedded using the /* embed */ comment.
  • false (exclusive) means that every URL is embedded, except those that are marked with /* noembed */ comment.
cssUrlEmbed: {
  encodeDirectly: {
    files: {
      'path/to/output.css': ['path/to/input.css']
    }
  }
}
cssUrlEmbed: {
  encodeWithBaseDir: {
    options: {
      baseDir: './app'
    },
    files: {
      'path/to/output.css': ['path/to/input.css']
    }
  }
}
cssUrlEmbed: {
  encode: {
    expand: true,
    cwd: 'target/css',
    src: [ '**/*.css' ],
    dest: 'target/css'
  }
}
cssUrlEmbed: {
  encode: {
    options: {
      skipUrlsLargerThan: '5 MB'
    },
  
    expand: true,
    cwd: 'target/css',
    src: [ '**/*.css' ],
    dest: 'target/css'
  }
}
.exclude-me {
  background-image: url('exclude_me.png'); /* noembed */
}
.include-me {
  background-image: url('include_me.png'); /* embed */
}
.include-me1 {
  background: transparent url('include_me.png') /* embed */ center center no-repeat;
}
 
.include-me2 {
  background-image: -webkit-image-set(url('include_me1.png') /* embed */ 1x, url('include_me2.png') /* embed */ 2x);
}
  • 1.5.1 / 2015-02-17
    • Fixed an issue that caused a file without embeddable URLs not to be written to destination folder.
    • Updated docs to clarify #21.
  • 1.5.0 / 2015-02-12
    • Added inclusive option. See docs.
  • 1.4.0 / 2014-12-27
    • Merged #17.
    • Updated dependencies.
  • 1.3.1 / 2014-11-22
  • 1.3.0 / 2014-11-21
    • Implemented #16.
  • 1.2.0 / 2014-11-14
    • Merged #14.
    • Updated dependencies.
  • 1.1.0 / 2014-10-01
    • Implemented #12.
    • Switched to MIME-type sniffing instead of just checking the extension of the file.
  • 1.0.4 / 2014-09-26
    • Implemented #11.
    • Merged #10.
  • 1.0.3 / 2014-09-05
    • Fixed #8.
  • 1.0.2 / 2014-09-03
    • Fixed #7.
    • Project cleanup.
  • 1.0.1 / 2014-08-23
    • Fixed #6.
  • 1.0.0 / 2014-07-23
    • The build will now fail if the file referenced by the URL is missing. Set failOnMissingUrl to false to disable this.
    • Replaced excluding by file extension with excluding through a comment in the CSS file.
  • 0.1.4 / 2014-05-14
    • Added an option to exclude certain file extensions.
  • 0.1.3 / 2014-01-29
    • Fixed handling of URL's with parameters.
    • Improved logging.
  • 0.1.2 / 2013-10-02
    • Changed logging a bit.
  • 0.1.1 / 2013-09-17
    • Removed dependency on datauri.
    • Now pretty much all MIME-types are supported.
  • 0.1.0 / 2013-09-09
    • First version.