grunt-extract-styles

Extract styles from css file based on decelerations matching.

Getting Started

This plugin requires Grunt ~0.4.2

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-extract-styles --save-dev

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

grunt.loadNpmTasks('grunt-extract-styles');

The "extractStyles" task

Overview

1. In your project's Gruntfile, add a section named extractStyles to the data object passed into grunt.initConfig().
2. In your HTML file add to style href url the suffix ?__extractStyles=extracted-style-filename.css.

Options

options.pattern

Type: RegExp

Mandatory parameter, the pattern that matchs the declaration for the extracted styles.

options.remove

Type: Boolean Default value: true

Whether or not to remove the matching declarations from the original stylesheet.

options.preProcess

Type: function Default: null

Pre-process function that apply on the matched by identifierPattern source file content

options.postProcess

Type: function Default: null

Post-process function that apply on the output content files (original & extracted)

options.remainSuffix

Type: string Default: .remain

The filename suffix of the remaining content. (style.css => style.remain.css)

options.extractedFileSuffix

Type: string Default: '.extracted'

The filename suffix of the extracted content. (style.css => style.extracted.css) If the Link tag doesn't contains a file name for the extracted content, the file name will be the original filename with that suffix.

options.extractedSuffix

Type: string Default: ``

suffix for the extracted file link. (with extractedSuffix:"?inline=true" extracted.css => extracted.css?inline=true)

options.linkIdentifier

Type: string Default: ?__extractStyles

Identifier of the links in the HTML to extract from. This string will convert to the following Regex:

'<link.*href="(.*' + linkIdentifier + '(?:=([^"]+))?)".*>'

options.usemin

Type: boolean Default: false

If true the plugin will try to add the remain file to the last css block.

Note: If there is no usemin css block you can add an empty css block.

    <!-- build:css({.tmp}) main.css -->
    <!-- endbuild -->
    <link href="style.css?__extractStyles=inline.css" rel="stylesheet" />

Will extract the css declerations from style.css, save them to inline.css and style.remian.css file will be added to main.css concat & minified.

For example if your options are:

{
    options: {
        pattern: /\[\[[^\]]+\]\]/,
    },
    files: [{
        dest: '.tmp/',
        src: '*.html'
    }]
}

And you apply it to the following:

@media screen and (min-width: 50em) {
    .rtl .thing {
        width: 100%;
        color: [[ some-param ]];
    }
 
   .another .thing {
        color: blue;
    }
}

This will be extracted:

@media screen and (min-width: 50em) {
    .rtl .thing {
        color: [[ some-param ]];
    }
}

Usage Examples

Splitting Wix tpa params into their own stylesheet

Gruntfile:

grunt.initConfig({
  extractStyles: {
            wixStyle: {
                options: {
                    pattern: /\[\[[^\]]+\]\]/,
                    preProcess: function (css) {
                        // wix tpa params uses {{}}, this breaks the parsers. convert them to [[]].
                        var ret = css.replace(/font:;{{([^}]+)}};/g, 'font: [[$1]];');
                        ret = ret.replace(/{{([^}]+)}}/g, '[[$1]]');
                        return ret;
                    },
                    postProcess: function (css) {
                        // wix tpa params uses {{}}, convert back the [[]] to {{}}.
                        var ret = css.replace(/font: \[\[([^\]]+)\]\];/g, '{{$1}};');
                        ret = ret.replace(/\[\[([^\]}]+)\]\]/g, '{{$1}}');
                        return ret;
                    },
                    extractedSuffix: '?__inline=true'
                },
                src: '*.html',
                dest: '.tmp/'
            }
        }
});

index.html

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title>Demo</title>
    <link href="style.css?__extractStyles=wix-styles.css" rel="stylesheet" />
</head>
<body></body>
</html>

style.css

.tpa-first:hover {
    color: {{tpa-color-1}};
    margin-left: 10px;
}
.tpa-second {
    border: 1px solid #000;
    font:;{{Body-M}}; //special case of wix tpa params
}
.no-tpa {
    border: 1px solid #000;
}
.only-tpa {
    color: {{tpa-color-2}};
}
 
@media (min-width: 300px) and (max-width: 730px) {
    .tpa-first:hover {
        color: {{tpa-color-1}};
        margin-left: 10px;
        padding: 5px 2px 5px 2px;
    }
    .tpa-second {
        border: 1px solid #000;
        font:;{{Body-M}};
    }
    .no-tpa {
        border: 1px solid #000;
    }
    .only-tpa {
        color: {{tpa-color-2}};
    }
}
.in-the-middle {
    width: 100%;
}
@media (min-width: 300px) and (max-width: 730px) {
    .tpa-first:hover {
        width: {{ tpa-width }};
    }
}

Will generate in .tmp folder to following files:

.tmp/index.html

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title>Demo</title>
    <link href="style.remain.css" rel="stylesheet" />
    <link href="wix-style.css?__inline=true" rel="stylesheet" />
</head>
<body></body>
</html>

.tmp/style.remain.css

.tpa-first:hover {
    margin-left: 10px;
}
.tpa-second {
    border: 1px solid #000;
}
.no-tpa {
    border: 1px solid #000;
}
 
@media (min-width: 300px) and (max-width: 730px) {
    .tpa-first:hover {
        margin-left: 10px;
        padding: 5px 2px 5px 2px;
    }
    .tpa-second {
        border: 1px solid #000;
    }
    .no-tpa {
        border: 1px solid #000;
    }
}
.in-the-middle {
    width: 100%;
}

.tmp/wix-styles.css

.tpa-first:hover {
    color: {{tpa-color-1}};
}
.tpa-second {
    {{Body-M}};
}
.only-tpa {
    color: {{tpa-color-2}};
}
 
@media (min-width: 300px) and (max-width: 730px) {
    .tpa-first:hover {
        color: {{tpa-color-1}};
    }
    .tpa-second {
        {{Body-M}};
    }
    .only-tpa {
        color: {{tpa-color-2}};
    }
    .tpa-first:hover {
        width: {{ tpa-width }};
    }
}

Note: By default, the matching rules are removed from style.css (set by remove property).

Credit

Uses the excellent PostCSS for the actual CSS post-processing.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.