gulp-modernizr-wezom

:us: English | :ru: Русский

Gulp plugin for moderznir, Wezom studio version

Table of contents

• Key Features and Benefits
• Installation
• Example of use
• Methods and Properties of the Plugin
• Search for tests in .js and .css files
• Project info

Key Features and Benefits

• Modernizr v3 ⇒
• Full control over the building your modernizr.js
  • Explicit indication of tests that are required under any conditions
  • Automatic addition of tests from the incoming files of gulp task
  • Explicit specification of options that are required under any conditions
  • Automatic addition of Moderznizr options, if they are needed for assembly tests
  • The ability to add custom tests and rewrite "native" tests "Modernizr"
  • Ability to exclude unwanted tests
• Correct search of tests in .js and .css files

Installation

npm i --save gulp-modernizr-wezom
# or using yarn cli
yarn add gulp-modernizr-wezom

Example of use

const gulp = require('gulp');
const gulpModernizrWezom = require('gulp-modernizr-wezom');

gulp.task('modernizr', function() {
    let src = [
        './dist/**/*.css', // The incoming files in which the tests will be searched
        './dist/**/*.js', // The incoming files in which the tests will be searched
        '!./dist/**/modernizr.js' // Exception of the file of Modernizr library itself
    ];

    return gulp.src(src)
        .pipe(gulpModernizrWezom({
            tests: [ // add tests forcibly
                'touchevents',
                'ambientlight',
                'adownload',
                'canvasblending'
            ],
            customTests: './my-feature-detects/custom-tests/', // path to the custom tests
            excludeTests: [ // exclude unwanted tests
                'opacity',
                'checked'
            ],
             options: [ // add options to the Modernizr library core
                 'setClasses',
                 'mq'
             ],
             minify: true // minify the final file of modernizr.js
        }))
        .pipe(gulp.dest('./dist/')); // save the resulting file modernizr.js
});

Methods and Properties of the Plugin

gulpModernizrWezom.pluginName

String property. Name of the plug-in

gulpModernizrWezom.pluginVersion

String property. The version of the plug-in

gulpModernizrWezom.getMetadata() → {Array.<Object>}

The method returns metadata of "native" tests of Modernizr as an array

gulpModernizrWezom.getCustomMetadata (customTests) → {Array.<Object>}

The method returns the metadata of the "custom" tests of the Modernizr as an array.

Parameters

Name | Type | Description --- | --- | --- customTests | string | The relative path from the current working directory (process.cwd()) to the directory with your user tests. For more details see customTests

gulpModernizrWezom( [config] )

Building modernizr.js.
The method accepts a configuration, based on which, it searches for the tests in the incoming files

After - build the file modernizr.js. Even if no tests are specified or detected - the file modernizr.js will still be created, with the core of the library.

Configuration

tests

data type Array.<string>
by default []

A list of tests that can be specified as mandatory. If such tests are not available in the incoming files, they will be added to the assembly in the same manner.

You should specify the names of the tests, as they are specified in the metadata of each test (the property key).
For example, a test canvas/blending.js has the meaning canvasblending.

There are some test files that have multiple tests in one file. For example canvas/todataurl.js Includes 3 tests ["todataurljpeg", "todataurlpng", "todataurlwebp"]. If necessary, include any of the three - the rest will also be added, since this is one file.

Example

const gulp = require('gulp');
const gulpModernizrWezom = require('gulp-modernizr-wezom');

gulp.task('modernizr', function() {
    let src = [
        './dist/**/*.css',
        './dist/**/*.js',
        '!./dist/**/modernizr.js'
    ];

    return gulp.src(src)
        .pipe(gulpModernizrWezom({
            tests: [
                'touchevents',
                'ambientlight',
                'adownload',
                'canvasblending'
            ],
        }))
        .pipe(gulp.dest('./dist/'));
});

customTests

data type string
by default undefined

The relative path from the current working directory (process.cwd()) to the directory with your user tests

There are several points that you must follow and know in order to correctly include your tests in the general build:

1. Within the directory, only js files should be located.
2. You must specify the path to the parent directory of all tests, inside you can break your tests into sub-directories, they will be included as well.
3. The path to your directory should NOT contain a directory named feature-detects, as an example you can use the name my-feature-detects
4. You can specify only one path to the directory you need
5. Each test file must have the correct file structure, in order to correctly build the metadata Modernizr. File sample - my-feature-detects/sample.js, sample user test - my-feature-detects/custom-tests/android.js
6. If you specify the name of the test, which is already in the list of "native" tests of Modernizr - then you will rewrite it with your own.

excludeTests

data type Array.<string>
by default []

A list of tests that should be excluded from the assembly, under any circumstances.
The name rules are the same as for the tests property

Example

const gulp = require('gulp');
const gulpModernizrWezom = require('gulp-modernizr-wezom');

gulp.task('modernizr', function() {
    let src = [
        './dist/**/*.css',
        './dist/**/*.js',
        '!./dist/**/modernizr.js'
    ];

    return gulp.src(src)
        .pipe(gulpModernizrWezom({
            tests: [
                'touchevents',
                'ambientlight',
                'adownload',
                'canvasblending'
            ],
            customTests: './my-feature-detects/custom-tests/',
            excludeTests: [
                'opacity',
                'checked'
            ]
        }))
        .pipe(gulp.dest('./dist/'));
});

classPrefix

data type string
by default undefined

A string that is added before each CSS class.

For example, if you specify classPrefix: 'supports-', then Modernizr will add CSS classes to the html element with this prefix, like as supports-no-ambientlight supports-canvas.

Also read the section Search for tests in .js and .css files, for more information.

options

data type Array.<string>
by default []

A list of options that can be added to build the Modernizr.

• Full list of options - https://github.com/Modernizr/Modernizr/blob/master/lib/config-all.json#L3
• Description of the majority of options - https://modernizr.com/docs/#modernizr-api

If additional options are required for certain tests, they will be added automatically (based on the metadata of each test, for example hasEvent will be automatically added during the test ambientlight)

Example

const gulp = require('gulp');
const gulpModernizrWezom = require('gulp-modernizr-wezom');

gulp.task('modernizr', function() {
    let src = [
        './dist/**/*.css',
        './dist/**/*.js',
        '!./dist/**/modernizr.js'
    ];

    return gulp.src(src)
        .pipe(gulpModernizrWezom({
            tests: [
                'touchevents',
                'ambientlight',
                'adownload',
                'canvasblending'
            ],
            customTests: './my-feature-detects/custom-tests/',
            excludeTests: [
                'opacity',
                'checked'
            ],
            options: [
                'setClasses',
                'mq'
            ]
        }))
        .pipe(gulp.dest('./dist/'));
});

minify

data type boolean
by default false

Minify the resulting file modernizr.js.

You can also use alternative methods for minimization, for example using gulp-uglify and, if need, gulp-sourcemaps

Example

const gulp = require('gulp');
const gulpModernizrWezom = require('gulp-modernizr-wezom');
const gulpUglify = require('gulp-uglify');
const gulpSourcemaps = require('gulp-sourcemaps');

gulp.task('modernizr', function() {
    let src = [
        './dist/**/*.css',
        './dist/**/*.js',
        '!./dist/**/modernizr.js'
    ];

    return gulp.src(src)
        .pipe(gulpModernizrWezom({
            tests: [
                'touchevents',
                'ambientlight',
                'adownload',
                'canvasblending'
            ],
            customTests: './my-feature-detects/custom-tests/',
            excludeTests: [
                'opacity',
                'checked'
            ],
            options: [
                'setClasses',
                'mq'
            ]
        }))
        
        .pipe(gulpSourcemaps.init())
        .pipe(gulpUglify({
            mangle: {
            	reserved: ['Modernizr']
            }
        }))
        .pipe(gulpSourcemaps.write('/'))
        
        .pipe(gulp.dest('./dist/'));
});

Search for tests in .js and .css files

To search for the necessary tests, the content of each incoming file is used. Text content is tested by regular expressions, which are compiled for each of the tests.

If a match is found, the test is added to the general build.

CSS files

To find the tests, plugin use the following regular expression:

/\.(no-)?TEST\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g

TEST - name of each test in the loop.
A few examples:

/\.(no-)?adownload\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.(no-)?canvas\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.(no-)?cssanimations\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.(no-)?opacity\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.(no-)?touchevents\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
// ...

If you use the property classPrefix, then the search for the tests in CSS files will also be performed taking into account the value of this property.

An example of a regular expression for searching, if classPrefix: 'supports-'

/\.supports-(no-)?adownload\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.supports-(no-)?canvas\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.supports-(no-)?cssanimations\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.supports-(no-)?opacity\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
/\.supports-(no-)?touchevents\b[^-](((?![\{|\}]).|(\r)?\n)*)\{/g
// ...

JS files

Property classPrefix - does not affect the search in js files.
To find the tests, plugin use the following regular expression:

/Modernizr\.TEST\b[^-]/g

TEST - name of each test in the loop.
A few examples:

/Modernizr\.adownload\b[^-]/g
/Modernizr\.canvas\b[^-]/g
/Modernizr\.cssanimations\b[^-]/g
/Modernizr\.opacity\b[^-]/g
/Modernizr\.touchevents\b[^-]/g
// ...

Project Info

• Change log
• Contributing Guidelines
• Contributor Covenant Code of Conduct
• License MIT