grunt-css-url-embed
v1.11.1
Published
Embed URL's as base64 strings inside your stylesheets
Downloads
3,024
Maintainers
Readme
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.
Getting Started
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');
cssUrlEmbed task
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.
Options
baseDir
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
.
failOnMissingUrl
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.
skipUrlsLargerThan
Type: String
Default: No restrictions
Skip URLs that are larger than the specified value.
For example: '5 MB'
, '30 KB'
, '300 B'
.
inclusive
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.
useMimeTypeSniffing
Type: Boolean
Default: true
Should we try to use the mmmagic
MIME-type sniffing library or should we always determine MIME-type only from the extension of the URL?
When set to false
the extension checking is always used. When set to true
it will first try use the mmmagic
library. However, in case the library failed to install it will fallback to extension checking.
Usage Examples
Map input and output files directly
cssUrlEmbed: {
encodeDirectly: {
files: {
'path/to/output.css': ['path/to/input.css']
}
}
}
Specify base directory if needed
cssUrlEmbed: {
encodeWithBaseDir: {
options: {
baseDir: './app'
},
files: {
'path/to/output.css': ['path/to/input.css']
}
}
}
Process all CSS files in target directory
cssUrlEmbed: {
encode: {
expand: true,
cwd: 'target/css',
src: [ '**/*.css' ],
dest: 'target/css'
}
}
Exclude URLs by size
cssUrlEmbed: {
encode: {
options: {
skipUrlsLargerThan: '5 MB'
},
expand: true,
cwd: 'target/css',
src: [ '**/*.css' ],
dest: 'target/css'
}
}
Disable MIME-type sniffing in favor of extension checking
cssUrlEmbed: {
encode: {
options: {
useMimeTypeSniffing: false
},
expand: true,
cwd: 'target/css',
src: [ '**/*.css' ],
dest: 'target/css'
}
}
Excluding URLs manually (when inclusive: false
)
.exclude-me {
background-image: url('exclude_me.png'); /* noembed */
}
Including URLs manually (when inclusive: true
)
.include-me {
background-image: url('include_me.png'); /* embed */
}
When URLs are in the middle of CSS property
.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);
}
Release History
- 1.11.1 / 2018-08-20
- Fixed #33.
- 1.11.0 / 2018-08-18
- Merged #32.
- 1.10.0 / 2017-01-19
- Fixed #31.
- 1.9.0 / 2017-01-18
- Fixed #30.
- 1.8.0 / 2016-12-01
- Merged #29.
- 1.7.0 / 2016-09-27
- Fixed #28.
- Updated dependencies.
- 1.6.1 / 2015-07-23
- Fixed #26.
- 1.6.0 / 2015-05-30
- Implemented #24.
- 1.5.2 / 2015-04-22
- Fixed #23.
- 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.
- Added
- 1.4.0 / 2014-12-27
- Merged #17.
- Updated dependencies.
- 1.3.1 / 2014-11-22
- Merged #17.
- 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
- 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
tofalse
to disable this. - Replaced excluding by file extension with excluding through a comment in the CSS file.
- The build will now fail if the file referenced by the URL is missing. Set
- 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.