Gulp JCrush CSS

Deduplicates a CSS file using Javascript.

It creates a compressed Javascript file (or inline code) that sets your styles and then modifies your HTML file to use that instead of your original CSS.

This is intended to be applied after your regular CSS minifier.

Uses JCrush, see that project for more info (and an in-built plugin for compressing Javascript files).

If you'd like to optimise your HTML output (more than minifiers), see also HyperCrush.

Installation

This is a Node.JS module available from the Node Package Manager (NPM).

https://www.npmjs.com/package/gulp-jcrushcss

Here's the command to download and install from NPM:

npm install gulp-jcrushcss -S

or with Yarn:

yarn add gulp-jcrushcss

Usage

In your gulpfile.mjs, use JCrush CSS as a Gulp plugin:

Step 1: Import JCrush CSS

import jcrushCSS from 'gulp-jcrushcss';

Step 2: Create a Gulp Task for JCrush

gulp.task('jcrushcss', () => {
  return gulp.src('styles.min.css')
    .pipe(jcrushCSS({
      html: ['index.html'], // This part is important
    }));
});

Step 3: Run JCrush CSS After Minification

To run JCrush CSS after your minification tasks, add JCrush CSS in series after other tasks, such as in this example:

gulp.task('default', gulp.series(
  gulp.parallel('minify-css', 'minify-js', 'minify-html'), // Run your minification tasks first
  'jcrushcss' // Then run JCrush CSS
));

Alternatively you can mix it in with your existing minification task, after your CSS is minified and renamed as usual.

Parameters

opts (Object, optional)

A configuration object with the following properties:

• html (Boolean, default: []): An array of HTML filenames (usually just one), where JCrush CSS will do its business. You SHOULD put this in, or the plugin will have a guess at which file to change, or just fail.

• inline (Boolean, default: false):

  • If true, JCrush CSS will inline its code into the HTML instead of referencing a file. Your code should definitely be minified first as it cannot contain line breaks. If your document relies on the styles to be present in order to display correctly this is a pretty reasonable option to turn on. If size optimization is your goal, this option has the shortest output.
  • If false, JCrush CSS will point to a file.

• appendExt (Boolean, default: true):

  • If true, JCrush CSS will create a js file with the ".js" appended to the name of your CSS file.
  • If false, JCrush CSS will replace the ".css" extension with ".js" - more likely to conflict with an existing file?

• rename (String, default: null):

  • Optionally specify an output filename (overrides appendExt).

• wrap (String, default: eval):

  • If eval, JCrush will use eval() for executing code strings, which has shorter output.
  • If newFunc, JCrush will use new Function() instead, which may be more secure in some environments.
  • If custom, JCrush will use options customPre and customPost to wrap the code string.

• let (Boolean, default: false):

  • If true, JCrush CSS will use the let keyword for variable declarations.
  • If false, it will create global variables without preceeding with any keyword, for shorter output.

• semi (Boolean, default: false):

  • If true, JCrush CSS will put a semi-colon at the end of the file.
  • If false, no semi-colon, for shorter output.

• strip (Boolean, default: true):

  • If true, JCrush CSS will strip escaped newlines and any adjacent whitespace from input.
  • If false, will retain the input as-is.

• reps (Number, default: 0):

  • Used to set a maximum number of compression replacements.

• prog (Boolean, default: true):

  • If true, JCrush CSS will output console messages about each replacement.
  • If false, will work silently.

• fin (Boolean, default: true):

  • If true, JCrush CSS will output final console messages about bytes saved or failure.

  • If false, will remain silent.

  • customPre (String, default: ''): Supply a custom string to prepend to the main code string. Used when wrap is set to custom.

• customPost (String, default: ''): Supply a custom string to append to the main code string. Used when wrap is set to custom.

Additionally, you can alter compression behavior:

• maxLen (Number, default: 40): The maximum length of substrings to consider. Setting this higher will slow things down.
• omit (Array, default: []): An array of substrings to omit from deduplication. Can be used to ignore accepted long/frequent words.
• clean (Boolean, default: false): If true, Strips symbols from input. Keep it false to dedupe all code, set it to true to focus only on words.
• words (Boolean, default: false): If true, matches whole words which speeds up processing. When false finds more compression opportunities but performs very poorly.
• trim (Boolean, default: false): If true, won't dedupe white space. When false finds more compression opportunities.
• break (Array, default: []): An array of substrings by which to split input. The break substring won't be matched. This can be used to concatenate an array of texts with a special char.
• split (Array, default: [':', ';', ' ', '"', '.', ',', '{', '}', '(', ')', '[', ']', '=']): Splits input after specified strings and may include them in matches as well as any whitespace afterwards. Setting these up properly for your particular input is key to balancing the effectiveness of compression vs the efficiency of execution time. The more splits in input the more compression opportunities are found, whereas fewer splits executes much faster but won't compress as much.
• escSafe (Boolean, default: true): Will take extra care around escaped characters. You'll probably want to keep this.

Unnecessary Reprocessing

To prevent unnecessarily reprocessing files consider using gulp-changed, gulp-cached, or gulp-newer.

Contributing

https://github.com/braksator/gulp-jcrushcss

In lieu of a formal style guide, take care to maintain the existing coding style.