grunt-css-urls

Grunt task to make css urls relative to a main css file with @import rules.

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-css-urls

Then add this line to your project's grunt.js gruntfile:

grunt.loadNpmTasks('grunt-css-urls');

finally define the task indicating where the css with the @import rules is located:

grunt.initConfig({
    cssurls: {
        files: {"build/site.css": "public/site.css"}
    }
});

Read the scenario described below to better understand how this task works combined together with the [grunt-css][grunt_css] task.

The Scenario

Lets imagine the following folder structure and css contents:

public
├── build
├── css
│   └─── common.css
│   └─── views
│   |    └── products
│   |         └── show.css
│   |         └── img
│   |              └── product-icon.png
├── img
|   └── logo.png
|   └── arrow.png
├── vendor
│   └─── jquery-plugin
│        └── css
│             └── jquery-plugin.css
│             └── images
│                  └── plugin.png

common.css

h1.logo { url('../img/logo.png') }

show.css

.product-icon { url('img/product-icon.png') }
.product-table .arrow { url('../../../img/arrow.png') }

jquery-plugin.css

.jquery-plugin { url('images/jquery-plugin.png') }

and the html file including the css inclussions:

<link media="screen" rel="stylesheet" type="text/css" href="/public/css/common.css">
<link media="screen" rel="stylesheet" type="text/css" href="/public/css/views/productos/show.css">
<link media="screen" rel="stylesheet" type="text/css" href="/public/vendor/jquery-plugin/css/jquery-plugin.css">

The Bundling Issue

If we want to bundle all the thing into a sinle file e.g.: /public/site.css including the three css files described above, the images' references will not work as they will be now relative the new /public folder.

The Solution

To solve the bundling issue we'll create a site.css file inside the public folder at the same level of css, img and vendor folders taking advantage of the @import css rules:

@import './public/css/common.css';
@import './public/css/views/productos/show.css';
@import './public/vendor/jquery-plugin/css/jquery-plugin.css';

and reference it in the html:

<link media="screen" rel="stylesheet" type="text/css" href="/public/site.css">

By doing this we'll have a reference starting point to calcule the relative urls for the url references inside the css files and replace those with the corresponding location.

And here is where the grunt-css-url task will do the magic. The following sample uses also the [grunt-cssjoin][grunt_cssjoin] task to join the css files into a site.all.css file:

var path = require('path');

module.exports = function(grunt) {
    grunt.initConfig({
        cssurls: {
            src:  {
                'public/site.urls.css' : 'public/site.css'
            }
        },
        cssjoin: {
            join: {
                files: {
                    'public/site.all.css' : 'public/site.urls.css'
                }
            }
        }, 
    });

    grunt.loadNpmTasks('grunt-cssjoin');
    grunt.loadNpmTasks('grunt-css-urls');

    grunt.registerTask('release', [ 'cssurls', 'cssjoin' ]);
};

Based on the scenario described above, the url references in public.join.css will end up like this:

h1.logo { url('./img/logo.png') }
.product-icon { url('./css/views/products/img/product-icon.png') }
.product-table .arrow { url('../../../img/arrow.png') }
.jquery-plugin { url('./vendor/jquery-plugin/css/images/jquery-plugin.png') }

mathroc/grunt-css-urls