node package manager
We need your input. Help make JavaScript better: Take the 2017 JavaScript Ecosystem survey »



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:


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

    cssUrls: {
        /* src *(required)*: The file location of the css with the @import rules. */
        src:  "public/site.css"

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

The Scenario

Lets imagine the following folder structure and css contents:

├── 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


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


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


.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 folowing sample uses also the grunt-css task to minify the css with the precedence defined in the site.css file:

var path = require('path');
module.exports = function(grunt) {
        cssUrls: {
            src:  "public/site.css"
        cssmin: {
            all: {
                dest: 'public/site.min.css',
                src: function () {
                    var content ='public/site.css').toString();
                    var files = [];
                    content.replace(/@import\s+'([^']+)/gim, function(match, location, a) {
                        files.push(path.resolve('public/' + location));
                    return files;
    grunt.registerTask('release', [ 'cssUrls', 'cssmin' ]);

Based on the scenario described above, the url references 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') }


Copyright (c) 2012 Juan Pablo Garcia & Ideame Dev Team Licensed under the MIT license.