Wulechuan's Printer For Errors of Glup Plugins

NPM Page

@wulechuan/printer-for-errors-of-gulp-plugins

Introduction

This package is renamed from @wulechuan/javascript-gulp-plugin-error-printer, as the old name is not so good.

This is a message logging tool for gulp. It parses gulp's PluginError instance, and is expected to print a more beautiful log for the error instance, as long as a parser is provided for that specific type of PluginError.

Almost all colors in the logs are configurable.

Supported Plugins So Far

• gulp-uglify
• gulp-stylus
• gulp-less
• gulp-sass
• gulp-postcss

Even for those errors that are not supported, a beautified property list is logged.

Usage

An Example

See the examples/gulpfile.js included by this repository as an example.

Below are the key snippet from the said gulpfile.js.

const printGulpPluginErrorBeautifully = require('@wulechuan/printer-for-errors-of-gulp-plugins');

const exampleSourceFileBasePath = '.';

const errorOfGlupPluginsPrintingConfigurations = {

    // This simply helps the logger print shorter paths
    // so that file paths looks better in narrow console windows.
    basePathToShortenPrintedFilePaths: exampleSourceFileBasePath,

    colorTheme: {
        heading: {
            lineColor: 'magenta',
        },
    },
};


function buildCSSStylus (cb) {
    return gulpRead(sourceGlobsOfCSSStylus)
        .pipe(compileStylus())
        .on('error', theError => {
            printGulpPluginErrorBeautifully(theError, errorOfGlupPluginsPrintingConfigurations);
            cb();
        });
}

An Example with gulp-pipe

The tasks in the new gulp (gulp 4), will throw as early as possible. So we have to handle the errors of each and every gulp-plugin like this.

At least that's the approach I know so far.

const printGulpPluginErrorBeautifully = require('@wulechuan/printer-for-errors-of-gulp-plugins');
const gulpPipeFromArray = require('gulp-pipe');



function aGulpTask() {
    const pipeSegments = [ gulp.src(sourceGlobs) ]


    // ---------------------------------------------------------------

    if (shouldEnableStylus) {
        const pipeInstance = stylus()

        // handle the error specific to "stylus".
        pipeInstance.on('error', theError => {
            printGulpPluginErrorBeautifully(theError, {
                basePathToShortenPrintedFilePaths: '../',
            })

            // Don't forget to end this pipe if an error occurs.
            // Otherwise, when used with gulp watcher,
            // the watcher gets hung for ever if this error occurs.
            pipeInstance.end()
        })

        pipeSegments.push(pipeInstance)
    }

    // ---------------------------------------------------------------


    if (shouldEnableAnotherPlugin) {
        const pipeInstance = anotherPlugin()

        // handle the error specific to this "anotherPlugin".
        pipeInstance.on('error', theError => {
            printGulpPluginErrorBeautifully(theError, {
                basePathToShortenPrintedFilePaths: '../',
            })

            // Don't forget to end this pipe if an error occurs.
            // Otherwise, when used with gulp watcher,
            // the watcher gets hung for ever if this error occurs.
            pipeInstance.end()
        })

        pipeSegments.push(pipeInstance)
    }


    pipeSegments.push(gulp.dest('./dist/css/'))



    return gulpPipeFromArray(pipeSegements)
}

Try It out, See It in Action

There is a dummy project included within this repository, so that people can try this logger without difficulty.

The said dummy project locates here:

<this repository root folder>/examples

Before You Try

Before you can start trying, you first need to install all dependencies for this npm project.

This is a one time action, you don't need to do it every time before you run the tryout script.

Open a console/terminal and run:

npm install

or even simpler:

npm i

Run the Tryout Script

Open a console/terminal and run:

npm start

or even simpler:

gulp

That's it.

Some Snapshots of Mine

Below are some snapshots of my console, hosted within Microsoft Visual Studio Code.

By the way, the used color theme of my Visual Studio Code, shown in the illustrates below, is the "Panda Theme".

A Stylus compilation error.

A LESSCSS compilation error.

A Sass compilation error.

An UglifyJS parsing error.

Configurations

Currently only colors are configurable. So you may call if "color theme configurations" if you prefer.

See configurations.md.

Known Issues

When utilizing the on('error') method of a gulp's pipeline, the error will propagate outside the event handler, and will finally get printed the traditional way. Since this logger also prints the error, the error is printed twice.

I'll learn how to swallow the error inside this logger in the future.

API

Sorry. I don't have too much spare time at present. I have my boy to take care of.

Consult my ugly source codes if you'd like to. :p