Postcss-bgimage NPM

postcss-bgimage

PostCSS plugin which removes background-image properties with url() values or leaves only its. It allows to separate your layouts CSS from the images CSS to boost a speed of showing a page.

:boom: Note! The plugin only removes CSS declarations. Do not expect cleaning empty rules after that. Use special plugins for it (csso, cssnano and other).

Installation

$ npm install postcss-bgimage --save-dev

$ yarn add postcss-bgimage --dev

Usage

Any way of using PostCSS. For example, Gulp PostCSS:

const gulp = require('gulp');
const postcss = require('gulp-postcss');
const rename = require('gulp-rename');
const bgImage = require('postcss-bgimage');

function noBackgrounds() {
  return gulp.src('css/style.css')
    .pipe(postcss([bgImage({ mode: 'cutter' })]))
    .pipe(rename({ suffix: '.top' }))
    .pipe(gulp.dest('compiled/css'));
}

function onlyBackgrounds() {
  return gulp.src('css/style.css')
    .pipe(postcss([bgImage({ mode: 'cutterInvertor' })]))
    .pipe(rename({ suffix: '.bottom' }))
    .pipe(gulp.dest('compiled/css'));
}

exports.compile = gulp.parallel(noBackgrounds, onlyBackgrounds);

Result

Common usage

Input

/* style.css */

body {
    background-image: url(/path/to/img.png);
    font-family: Arial;
    padding: 20px 10px;
}

Output

/* style.top.css */

body {
    font-family: Arial;
    padding: 20px 10px;
}

/* style.bottom.css */

body {
    background-image: url(/path/to/img.png);
}

Usage with shortcut `background`

Input

/* style.css */

#some {
    display: flex;
    background: #f30 url(/path/to/img.png) 50% no-repeat;
    color: #fff;
}

Output

/* style.top.css */

#some {
    display: inline-block;
    background: #f30 50% no-repeat;
    color: #fff;
}

/* style.bottom.css */

#some {
    background-image: url(/path/to/img.png);
}

Using in nested at-rules

Input

/* style.css */

@media (min-width: 320px) {
    .title + .list > li {
        background: url(/path/to/img.png);
    }

    @supports (display: flex) {
        .panel {
            display: flex;
            background: url(/path/to/img.png);
        }
    }

    .panel {
        display: block;
    }
}

Output

/* style.top.css */

@media (min-width: 320px) {
    .title + .list > li {
    }

    @supports (display: flex) {
        .panel {
            display: flex;
        }
    }

    .panel {
        display: block;
    }
}

/* style.bottom.css */

@media (min-width: 320px) {
    .title + .list > li {
        background: url(/path/to/img.png);
    }

    @supports (display: flex) {
        .panel {
            background: url(/path/to/img.png);
        }
    }

    .panel {
    }
}

Ignore rules

To ignore some CSS rules use comment /* bgImage: ignore */. For example:

Input

/* style.css */

.some-rule {
    display: inline-block;
    /* bgImage: ignore */
    background: url(/path/to/img2.png);
}

@media (min-width: 320px) {
    /* bgImage: ignore */
    @supports (--color: red) {
        .some-rule {
            background: url(/path/to/img2.png);
            color: var(--color);
        }
    }

    .some-rule {
        display: inline-block;
        background: url(/path/to/img2.png);
    }
}

Output

/* style.top.css */

.some-rule {
    display: inline-block;
    /* bgImage: ignore */
    background: url(/path/to/img2.png);
}

@media (min-width: 320px) {
    /* bgImage: ignore */
    @supports (--color: red) {
        .some-rule {
            background: url(/path/to/img2.png);
            color: var(--color);
        }
    }

    .some-rule {
        display: inline-block;
        background: url(/path/to/img2.png);
    }
}

/* style.bottom.css */

.some-rule {
}

@media (min-width: 320px) {
    /* bgImage: ignore */
    @supports (--color: red) {
        .some-rule {
        }
    }

    .some-rule {
    }
}

Using of the resulting files in HTML

<!doctype html>

<html>
    <head>
        <title>postcss-bgimage test</title>
        <link rel="stylesheet" href="/compiled/css/style.top.css">
    </head>

    <body>
        <h1>postcss-bgimage test</h1>
        <p>Page content</p>
    </body>
</html>
<link rel="stylesheet" href="/compiled/css/style.bottom.css">

Or (in a case of small size) you can inject top CSS in <head> with <style> to decrease the number of blocking HTTP requests.

<!doctype html>

<html>
    <head>
        <title>postcss-bgimage test</title>
        <style>/* Content of your /compiled/css/style.top.css */</style>
    </head>

    <body>
        <h1>postcss-bgimage test</h1>
        <p>Page content</p>
    </body>
</html>
<link rel="stylesheet" href="/compiled/css/style.bottom.css">

Options

mode

(required) Mode of the plugin.

cutter - Removes background-image: properties with external references through url() from source CSS.
cutterInvertor - Removes all CSS rules without background-image and leaves only this property for other ones.