Oxyz Build

Simple Gulp add-on for easy project building.

Usage

Simple step-by-step guide:

• Create the gulpfile.js file in the project’s root directory.
• Import the oxyz-build module.
• Export the result of calling the task function with necessary parameters.
• Run the file via the console (gulp)

For example:

const { action, task } = require( 'oxyz-build' );

module.exports.build = task([
	action.clean({ src: 'dist' }),
	action.copy({ src: [ 'dev/**/*.scss', 'dev/**/*.pug' ], dest: 'tmp' }),
	action.del({ src: 'tmp/**/*', marker: 'DIST' }),
	action.sass({ src: 'tmp/**/!(_)*.scss', dest: 'dist' }),
	action.pug({ src: 'tmp/components/page/!(_)*.pug', dest: 'dist' }),
	action.copy({ src: [ 'dev/**/*.js', 'dev/**/*.ico' ], dest: 'dist' }),
	action.minifyimg({ src: [ 'dev/**/*.jpg', 'dev/**/*.png' ], dest: 'dist' }),
	action.clean({ src: 'tmp' })
]);

API

set()

Creates an array of executable functions out of the action sequence for further transfer to gulp.series or gulp.parallel.

executableSet = set( actions );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actions | Array | yes | An array of the action set | | executableSet | Array | | Executable set of functions |

task()

Creates a gulp-task out of the action sequence. Afterward, it can be inserted into another task or exported.

series = task( actions );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actions | Array | yes | An array of the action set | | series | function | | Task series |

action.copy()

File copying.

actionObject = action.copy( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.src | string|Array | yes | glob file selection for copying | | options.dest | string|Array | yes | destination path |

action.clean()

File deletion.

actionObject = action.clean( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.src | string|Array | yes | glob file selection for deletion |

action.minifyimg()

Image minifying.

actionObject = action.minifyimg( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.src | string|Array | yes | glob image file selection for minifying | | options.dest | string|Array | no | Destination path (if not specified, source files will be overwritten) | | options.cache | boolean | no | Using cache during minifying (the result is cached and used repeatedly to save time) |

action.del()

Deleting a part of the file using markers.

actionObject = action.del( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.src | string|Array | yes | glob file selection | | options.dest | string|Array | no | Destination path (if not specified, source files will be overwritten) | | options.marker | string | yes | Marker name (digits, letters, uppercase, and underscore are acceptable) |

action.pug()

Compiling Pug files.

actionObject = action.pug( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.pug | object | no | pug compiler parameters | | options.src | string|Array | yes | glob file selection for compiling | | options.dest | string|Array | yes | Destination path | | options.debug | boolean | no | Shows the compiled file in the console |

action.sass()

Compiling Sass files.

actionObject = action.sass( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.sass | object | no | sass compiler parameters | | options.src | string|Array | yes | glob file selection for compiling | | options.dest | string|Array | yes | Destination path | | options.debug | boolean | no | Shows the compiled file in the console |

action.transform()

Transforming the file selection content.

actionObject = action.transform( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.src | string|Array | yes | glob file selection for processing | | options.dest | string|Array | no | Destination path (if not specified, source files will be overwritten) | | options.cb | function | yes | Transformation callback, gets the file content (contents & file), must return a string |

action.json()

Modifying the content of a JSON-file as an object.

actionObject = action.json( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.opts | object | no | gulp.src parameters | | options.fname | string|object|function | no | gulp-rename parameters | | options.src | string|Array | yes | glob file selection for processing | | options.dest | string|Array | no | Destination path (if not specified, source files will be overwritten) | | options.cb | function | yes | Transformation callback, gets an object, must return an object |

action.zip()

Packing the file selection into a zip archive.

actionObject = action.zip( options );

| parameter | type | required | description | |:---:|:---:|:---:|---| | actionObject | object | | Created action object for further execution | | options | object | yes | Action parameters | | options.name | string | no | Name of the action displayed in the console during execution | | options.cb | function | no | Executable callback (must be synchronous), does not accept parameters | | options.opts | object | no | gulp.src parameters | | options.zip | object | no | gulp-zip parameters | | options.fname | string | yes | Name of the zip archive | | options.src | string|Array | yes | glob file selection for processing | | options.dest | string|Array | no | Destination path, if not specified, then the archive will be created in the project’s root folder |

Custom action

A conditional action is a function of a gulp task or a simple object with the execute parameter that represents a gulp task, too.

Examples:

let action = function ( end ) {
  console.log( 'Hello world' );
  end();
};

let actionObject = {
  execute: function ( end ) {
    console.log( 'Hello world' );
    end();
  }
};

let actionObject = {
  execute: function () {
    return src( 'src/*.js' )
      .pipe( dest( 'output/' ) );
  }
};

To shorten the routine actions, a function that returns an action object can be used, for example:

/**
 * File copying
 * @param {object} data - object with parameters
 * @param {string|Array.<string>} data.src - glob file selection for copying
 * @param {string} data.dest - destination path
 * @return {object}
 */
let myCopy = function ( obj ) {
  // Checking for required parameters
  if ( !obj || !obj.src || !obj.dest ) throw Error( 'Required parameter of myCopy not specified (src, dest)' );

  // Gulp task for file copying with the received parameters obj.src and obj.dest
  obj.execute = function () {
    return src( obj.src ).pipe( dest( obj.dest ) );
  }

  // Changing the task name
  obj.execute.displayName = 'My Simple Copy';

  // Returning the action object
  return obj;
};

Now, a new action can be used:

const { action, task } = require( 'oxyz-build' );

module.exports.build = task([
	action.clean({ src: 'dist' }),
	myCopy({ src: [ 'dev/**/*.scss', 'dev/**/*.pug' ], dest: 'tmp' }),
	action.del({ src: 'tmp/**/*', marker: 'DIST' }),
	action.sass({ src: 'tmp/**/!(_)*.scss', dest: 'dist' }),
	action.pug({ src: 'tmp/components/page/!(_)*.pug', dest: 'dist' }),
	myCopy({ src: [ 'dev/**/*.js', 'dev/**/*.ico' ], dest: 'dist' }),
	action.minifyimg({ src: [ 'dev/**/*.jpg', 'dev/**/*.png' ], dest: 'dist' }),
	action.clean({ src: 'tmp' })
]);