@joinbox/build-task

Intro

Re-usable Gulp 4 tasks for Joinbox projects that cover the following file types:

• scripts
• styles
• templates
• images (TBD)

The tasks support:

• source maps
• notifications
• minification
• browser sync
• cache busting (TBD)
• etc.

Available Tasks

BuildTaskBuilder exposes the following tasks when using the default config:

General

• gulp: First clears your destination directory, then calls dev, then watchand then starts up a browserSync webserver
• gulp prod: Clears destination, then creates production files
• gulp serve: Just boots up and runs the server; changes won't be watched (as no watch tasks are started)
• gulp clean: Removes the destination folder

JS

• jsDev: Clears JS folder in destination, converts JS files, then halts
• jsWatch: Only watches JS files (triggers on change)
• js: jsDev then jsWatch
• jsProd: Clears JS folder in destination, converts and minifies files for production

CSS

• cssDev: Clears CSS folder in destination, converts css files, then halts
• cssWatch: Only watches CSS files (triggers on change)
• css: cssDev then cssWatch
• cssProd: Clears CSS folder in destination, converts and minifies files for production

HTML

• htmlDev: Clears HTML folder in destination, copies all HTML files
• htmlWatch: Only watches HTML files (triggers on change)
• html: htmlDev then htmlWatch
• htmlProd: Clears HTML folder in destination, converts and minifies files for production

Settings

See default settings. Can be changed with setConfig (see below).

Setup

1. Create a new folder

2. Install gulp 4 and build-task locally, gulp-cli globally:

   npm i -D @joinbox/build-task gulp@4 gulpjs/gulp-cli
   

3. Add a gulpfile.js …

   touch gulpfile.js
   

4. Add a start script to your package.json:

   {
        scripts: {
            start: 'node ./node_modules/gulp-cli/bin/gulp.js'
        }
   }
   
   

5. Either use the default config …

   const BuildTask = require('@joinbox/build-task');
   
   const builder = new BuildTask();
   module.exports = builder.createTasks();
   

6. … or adjust it to match your own setup:

   // Require and initialize our builder:
   const BuildTask = require('@joinbox/build-task');
   const builder = new BuildTask();
   
   // Update/change config. The configuration is an object; pass the path to the 
   // property you desire to change and set its new value. See src/defaultConfig
   // for defaults.
   builder.setConfig('paths.css.entryPoints', ['styles.scss']);
   builder.setConfig('paths.js.technologies', ['react']); 
   builder.setConfig('supportedBrowsers', ['>1%']);
   // Don't export the server gulp task; when calling gulp's default task, it won't 
   // start either
   builder.setConfig('server', false);
   
   // Create a custom task
   // imgDev copies images to destination directory
   // imgWatch watches changes on images and copies them to destination directory
   const imageSources = 'www/src/**/*.png';
   function imgDev() {
       return gulp.src(imageSources)
           .pipe(gulp.dest('www/dist'));
   }
   function imgWatch() {
       return gulp.watch(imageSources, imgDev);
   }
   
   // Add your tasks to builder.tasks: they will become part of the object returned by 
   // createTasks(). builder.tasks is a Map; the key is the tasks's name, the value the 
   // corresponding function. 
   // Your functions cann now be invoked by calling gulp imgWatch or gulp imgDev
   builder.tasks.set('imgWatch', imgWatch);
   builder.tasks.set('imgDev', imgDev);
   
   // Add your task to builder.devTasks and builder.watchTasks; this will call them 
   // within the default gulp task. devTasks and watchTasks are arrays.
   builder.devTasks.push(imgDev);
   builder.watchTasks.push(imgWatch);
   
   // Export tasks to expose them to gulp
   module.exports = builder.createTasks();
   

7. Run your tasks

   As you added your own imgWatch and imgDev functions to the gulp task, they will now be part of the default gulp task and therefore be invoked when executing:

   gulp
   

Paths

A word about PATHS:

• Paths are generated hierarchically from different config properties:
  • JS: path.join(paths.base, paths.source, scripts.paths.source) + every entry in scripts.paths.entries
  • CSS: path.join(paths.base, paths.source, styles.paths.source) + every entry in styles.paths.entries
• paths.base, paths.source, scripts.paths.source and styles.paths.source must be strings; they may be relative (to process.cwd()) or absolute.
• Use empty strings ('') if there is no common denominator between JS and CSS.
• Entries may be objects (JS) or arrays (JS and CSS), see webpack config

Tests

• There are a few automated tests, run them with npm test.
• To test a single gulp file, call the gulp files in the test folder:

    cd test && gulp -f gulpfile.default.js