dustman

v1.11.56

Published

2 years ago

A Gulp based front-end automation boilerplate that helps you to keep your builds clean

Downloads

d u s t m a n

Release 1.11.X details

Type | Description ------- | ---------------------------------------------------------- fix | First empty action of the build folder not works always fix | Restores javascript sourcemaps fix | Changes node dependencies for compatibility reasons fix | Update node dependencies feature | Build process is now integrated with desktop notifications

Gulp + YAML config based front-end automation boilerplate

Dustman is basically a set of Gulp tasks ready to be used as a build system which helps you to:

Build CSS

Build SASS or LESS autodetected with multiple themes.
Dynamic tasks with selective YAML configuration for every theme.
CSSlint tests.
StyleStats reports.
Autoprefixer for automated multiple browser support.
CSS vendors and assets already optimized for production environments.
Everything minimized in one file and with map support.

Build JavaScript

Apps with dependencies in sequence you need.
Everything minimized in one file and with map support.

Build HTML

Build Twig templates to HTML pages.
BrowserSync ready to be tested on multiple devices.
Faker ready to be used to add fake contents easily.
[Moment] ready to be used with faker to format dates easily.
HTML prettified to have consistently coded HTML templates.

Watch and Serve with HTTP server

Watch files automation tasks listeners to update your build automatically.
BrowserSync support to check CSS, JavaScript and HTML coded.

Gulp 4 alpha

At the moment Dustman is based on Gulp 4 which is in alpha release status so use it on your own risk! I didn't noticed any problems, but I didn't tested it in many environments.

Why Gulp 4?

Because it has a superior task concatenation system compared to the previous major release.
Because the watcher and the build system are faster.

Installation

The installation command will install dustman module in your package file and copy the dustman files to your project directory:

npm install --save dustman
cp -i ./node_modules/dustman/dustman.yml dustman.yml
cp -i ./node_modules/dustman/gulpfile.js gulpfile.js

The flag -i will prompt if you want to overwrite an existing file in the target directory.

Build suite

Dustman has a set of main tasks which uses a set of sub tasks in sequence.

Main tasks

The idea behind Dustman is to use a set of Gulp main tasks which shouldn't be changed, and decide how to build by adding or removing the sub tasks listed in the tasks YAML configuration.

Default

$ gulp

You can choose a different config by using --config paramter.

$ gulp --config another-config.yml

All tasks can run locally with ./node_modules/.bin/gulp taskname in the tasks table will be used gulp taskname to be easy to read.

$ ./node_modules/.bin/gulp --config another-config.yml --silent

Note: Tasks with --silent or -S flag will stop firing Gulp task logs, but you can miss errors not checked by dustman.

Watcher

If js.watch, css.watch and html.watch watched folder's files changes, the watcher will perform a new build.

$ gulp watch

The abbreviation command for watch is w

$ gulp w

Server + watcher

If js.watch, css.watch and html.watch watched folder's files changes, the watcher will perform a new build.

A server based on browser sync node module will serve the HTML templates.

$ gulp http

The abbreviation command for http is h

$ gulp h

Sub tasks

In the dustman.yml config, you can select the tasks (css, js or html) to be used to choose what will be built.

tasks:
  - css
  - js
#  - html # skip HTML tasks

Shell commands

You can run shell commands with shell parameters in config:

shell:
  before:
    - echo before build task command 01
    - echo before build task command 02
  after:
    - echo after build task command

JavaScript task file generator

If you use this YAML config:

js:
  file: dustman.min.js
  files:
    - my/js/development/file.js
  vendors:
    file: vendors.min.js
    merge: true
    files:
      - vendor/angular/angular.js

Dustman will generate these files:

dustman.min.js # [ dev files + vendors ]
dustman.no-vendors.min.js # [ dev files only ]
vendors.min.js # [ vendors only, used for caching vendors and skip its build time ]

If you use this YAML config:

js:
  file: dustman.min.js
  files:
    - my/js/development/file.js
  vendors:
    file: vendors.min.js
    merge: false
    files:
      - vendor/angular/angular.js

Dustman will generate these files:

dustman.min.js # [ dev files only ]
vendors.min.js # [ vendors only, will be generated only the first time ]

Config example

---

tasks:
  - css  # optional [skipped]
  - js   # optional [skipped]
  - html # optional [skipped]

config:
  autoprefixer: # optional [defaults]
    browsers:
      - last 3 versions
  csslint: csslintrc.json # optional [defaults]
  stylestats: .stylestatsrc # optional [defaults]
  prettify: # optional [defaults]
    indent_char: ' '
    indent_size: 2
  faker: # optional [defaults]
    locale: it
  twig: # optional [defaults]
    cache: false
  osNotifications: true # optional [true]
  emptyFolders: false # optional [true]
  polling: 500 # optional [false]
  verify: true # optional [false]
  verbose: 3 # optional [3]

css: # optional [required by sub task css if used]
  file: themes-with-vendors.min.css # optional [dustman.min.css]
  watch: my/sass/files/**/*.scss # optional [./**/*.scss]
  path: my/sass/path/ # optional [inherit path.css]
  themes:
    -
      name: theme-one # optional [theme-0]
      file: theme-one.css # optional [theme-0.css]
      compile: my/sass/files/theme-one/import.scss
      images: my/sass/files/themes/default/img/**/*.* # optional [skipped]
      fonts: my/sass/files/themes/default/img/**/*.* # optional [skipped]
      csslint: true # optional [false]
      path: my/sass/path/ # optional [inherit path.css]
      stylestats: true # optional [false]
      autoprefixer: true # optional [false]
    -
      name: theme-two # optional [theme-1]
      file: theme-two.css # optional [theme-1.css]
      compile: my/sass/files/theme-two/import.scss
      csslint: false # optional [false]
      stylestats: false # optional [false]
      autoprefixer: false # optional [false]
  vendors: # optional
    file: vendors.min.css
    merge: true  # optional [true]
    path: custom/path/ # optional [inherit path.css]
    files:
      - vendor/angular/angular-csp.css
      - vendor/angular-bootstrap/ui-bootstrap-csp.css
      - vendor/font-awesome/css/font-awesome.css
      - vendor/angular-chart.js/dist/angular-chart.css

js: # optional [required by sub task js if used]
  file: app-with-vendors.min.js # optional [dustman.min.js]
  watch: my/js/files/**/*.js # optional [./**/*.js]
  merge: true # optional [true]
  path: my/sass/path/ # optional [inherit path.js]
  files:
    - my/js/files/*
  vendors: # optional
    file: vendors.min.js
    path: custom/path/ # optional [inherit path.js]
    merge: true # optional [true]
    files:
      - vendor/angular/angular.js
      - vendor/angular-animate/angular-animate.js
      - vendor/angular-bootstrap/ui-bootstrap-tpls.js
      - vendor/angular-bootstrap/ui-bootstrap.js
      - vendor/Chart.js/Chart.js
      - vendor/angular-chart.js/dist/angular-chart.js
      - vendor/angular-cookies/angular-cookies.js
      - vendor/angular-dynamic-locale/dist/tmhDynamicLocale.js
      - vendor/angular-flash/angular-flash.js
      - vendor/angular-route/angular-route.js

shell: # optional [skipped]
  before: # optional [skipped]
    - echo before build task command 01
    - echo before build task command 02
  after: # optional [skipped]
    - echo after build task command

vendors: # optional [skipped]
  fonts: # optional [skipped]
    - vendor/font-awesome/fonts/fontawesome-webfont.eot
    - vendor/font-awesome/fonts/fontawesome-webfont.svg
    - vendor/font-awesome/fonts/fontawesome-webfont.ttf
    - vendor/font-awesome/fonts/fontawesome-webfont.woff
    - vendor/font-awesome/fonts/fontawesome-webfont.woff2
    - vendor/font-awesome/fonts/FontAwesome.otf
  images: # optional [skipped]
    - vendor/font-awesome/fonts/fontawesome-webfont.svg

html: # optional [required by sub task html if used]
  engine: twig # optional [html]
  fixtures: # optional [false]
    images: images.json
    foo: foo.json
  watch: test/examples/twig/**/*.twig
  files:
    - test/examples/twig/index.twig

paths:
  server: my/build/
  css: my/build/css/
  images: my/build/img/
  fonts: my/build/fonts/
  js: my/build/js/

Load a sub config file

Now it's possible to load config portions based on task type

---

tasks:
  - css
  - html
  - js

config: path/relative/to/this/config.yml
css: path/relative/to/this/config.yml
html: path/relative/to/this/config.yml
js: path/relative/to/this/config.yml
paths: path/relative/to/this/config.yml
vendors: path/relative/to/this/config.yml
shell: path/relative/to/this/config.yml

Config parameters

Config

Config parameters with links comes from related plug-in configurations

Parameter | Example value | Type | Description ------------------------ | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------- config | mixed | Object | It contains CSS options config.autoprefixer | mixed | Object | gulp-autoprefixer config.csslint | path/csslintrc.json | String | It contains CSSlint options path config.emptyFolders | true | Boolean | Deletes file contents inside paths.server to keep the build clean config.faker | mixed | Object | https://github.com/marak/Faker.js/ config.prettify | mixed | Object | https://www.npmjs.com/package/gulp-html-prettify config.stylestats | path/.stylestatsrc | String | It contains Stylestats options path config.twig | mixed | Object | gulp-twig config.osNotifications | true | Boolean | Enables OS desktop notifications config.polling | 500 | mixed | Set millisecs of polling to the Gulp watcher to prevent missing Vagrant NFS filesync with local system and VM, it's false by default config.verbose | 3 | Integer | The verbose value, 0: no messages, 3: all message logs config.verify | true | Boolean | Checks if all dustman generated files are created on the machine

CSS

Parameter --------------------------- css css.file css.path css.themes css.themes css.themes[].autoprefixer css.themes[].compile css.themes[].csslint css.themes[].file css.themes[].fonts css.themes[].images css.themes[].merge css.themes[].name css.themes[].path css.themes[].stylestats css.vendors css.vendors.file css.vendors.merge css.vendors.files css.watch | Example value | Type | Description | -------------------- | --------- | ---------------------------------------------------------------------------- | mixed | Object | It contains CSS options | dustman.min.css | String | The name of the merged and minified CSS with vendors and SASS or LESS themes | path/to/css/ | String | If this theme should be built in a specific folder | mixed | Array | It contains theme with it's config | mixed | Array | It contains theme object with it's config | true | Boolean | If the build will add prefixes to the CSS theme | -path/theme.sass | String | Path to the CSS theme, can be SASS or LESS | true | Boolean | If theme need to be tested | theme-name.min.css | String | The name of the single theme built | path/__/.** | String | Fonts path related to theme | path/__/.** | String | Images path related to theme | true | Boolean | If this theme should be in the final merged CSS file | theme-name | String | The name will be listed in the build logs, based on config.verbose | path/to/css/ | String | If this theme should be built in a specific folder | true | Boolean | If this theme is passed to stylestats report | mixed | Object | It contains CSS vendors options | vendors.min.css | String | The name of the merged and minified vendors CSS | true | Boolean | If vendors will be merged into the final CSS file | -vendors/file.css | Array | Files listed for the merged CSS vendors build | path/__/.js* | String | Files watched from the main task watcher

JavaScript

Parameter | Example value | Type | Description ------------------ | ------------------- | --------- | ----------------------------------------------------------------------------------------- js | mixed | Object | It contains JavaScript options js.file | dustman.min.js | String | The name of the merged and minified JavaScript js.path | path/to/js/ | String | If this theme should be built in a specific folder js.watch | path/__/.js* | String | Files watched from the main task watcher js.files | -path/file.js | Array | Files listed for the JavaScript build, it can also be a conatiner path like -path/app/* js.vendors | mixed | Object | It contains CSS vendors options js.vendors.file | vendors.min.js | String | The name of the merged and minified vendors JS js.vendors.merge | true | Boolean | If vendors will be merged into the final JS file js.vendors.files | -vendors/file.css | Array | Files listed for the merged JS vendors build

Paths

Parameter | Example value | Type | Description -------------- | ---------------------- | -------- | -------------------------------------------------------------------------------------- paths | mixed | Object | It contains build path targets paths.server | path/to/html/ | String | Path where the Browser sync local server will point and Twig will be generated paths.css | path/to/html/css/ | String | Where CSS files will be moved from source targets to the production folders paths.images | path/to/html/images/ | String | Where images files will be moved from source targets to the production folders paths.fonts | path/to/html/fonts/ | String | Where fonts files will be moved from source targets to the production folders paths.js | path/to/html/js/ | String | Where js files will be moved from source targets to the production folders

Shell

Shell node module doesn't seems to support every command

Parameter | Example value | Type | Description -------------- | --------------- | -------- | ------------------------------------------------------------------- shell | mixed | Object | It contains shell tasks options shell.before | -bash command | Array | Bash commands will be executed in series before the build tasks shell.after | -bash command | Array | Bash commands will be executed in series after the build tasks

Tasks

Parameter | Example value | Type | Description --------- | ------------- | ------- | ------------------------------------------------- tasks | -css | Array | It contains the sub tasks pipeline build sequence

You can add css, js and html

HTML

Parameter | Example value | Type | Description --------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ html | mixed | Object | It contains twig options html.engine | twig | String | The engine used, Twig or HTML for now (html by default) html.watch | path/__/.twig* | String | Files watched from the main task watcher html.files | -path/file.twig | Array | Files listed for the HTML build html.fixtures | mixed | Object | A list of property which points to json files that will be loaded with the same property name, if you set fixtures.images to images.json in the twig you'll get json contents {{ fixtures.images[0].title }}

Vendors

Parameter | Example value | Type | Description ---------------- | -------------------- | -------- | ---------------------------------------------------- vendors | mixed | Object | It contains vendors options vendors.fonts | -vendors/font.ttf | Array | Files listed to be moved on fonts production folder vendors.images | -vendors/image.svg | Array | Files listed to be moved on images production folder

Previous release details

Release 1.10.X details

Type | Description ------- | ---------------------------------------------------------------------------------------------- fix | Skips removing build folder if it's the first build process fix | Check if emptyFolders is set to prevent removed vendors after the first build of the watcher feature | Build folders are automatically emptied, can be skipped with confing.emptyFolders

Release 1.9.X details

Type | Description ------------ | --------------------------------------------------------------------------------------------- fix | Fixes fixtures path optimization | Now you can load configs for config, paths, tasks, shell and vendors properties too feature | TWIG can load json fixtures

Release 1.8.X details

Type | Description ------- | ------------------------------ feature | Config can load another config

Release 1.7.X details

Type | Description ------------ | -------------------------- optimization | Updates node packages fix | Fix css task when not used feature | Adds moment to twig

Release 1.6.X details

Type | Description ------ | ---------------------------------------------------------------- change | Moves to node_modules temp folders no-vendors.js file when built

Release 1.5.X details

Type | Description ------------ | ---------------------------------------------------------------------------------- fix | Wrong polling settings if disabled fix | Now JS task can be with vendors only fix | Adds a missing warning if -S flag is passed to Gulp task optimization | Adds abbreviation command for Gulp's http task, now can be called just with h optimization | Adds abbreviation command for Gulp's watch task, now can be called just with w fix | Corrects a wrong file check on CSS task for verify task fix | Ensure CSS and JS tasks can be empty also on files verify task fix | Ensure HTML task can be empty also on files verify task optimization | Files list concatentation is more easy to read optimization | Adds toString to message logs optimization | Adds toString to path errors optimization | Now vendors are disabled by default to ensure CSS and JS vendors to be optional fix | CSS and JS vendors now are optional fix | Fix wrong file path on JS vendors save feature | Adds additional path properties to css and js tasks

Release 1.4.X details

Type | Description ------------ | ------------------------------------------------------------------- fix | Check between system node version and required version correctly fix | Removed old task name twig for html to verify files correctly optimization | Add system node version check to notify if it's too old optimization | Add timed to important messages to be more easy to read fix | Fix wrong task error for watched dustman folders fix | Fix missing config file message optimization | Added missing vendors warning if it's thrown a file not found error test | Added travis tests feature | Added engine selection for HTML build

Release 1.3.X details

Type | Description ------- | ----------------------------------------------------------------------------------------------------- feature | Added polling option to Gulp watcher to prevent missing Vagrant NFS filesync with local system and VM

Release 1.2.X details

Type | Description --------------- | ----------------------------------------------------------------------------- fix | Optimized files verification to be of their relative task modules coding standard | Remove unused comments fix | Fix shell tasks not started properly feature | Now it's possible to verify files built to ensure everything work as expected

Release 1.1.X details

Type | Description ------------ | ----------------------------------------------------------------------- optimization | If JS or CSS vendor files are removed they will be built again fix | Fix wrong name notice log for fonts vendors fix | Fix vendors assets always skipping from build fix | Fix wrong default JavaScript path for vendors fix | Decommented missing minimized JavaScript files optimization | Task logs are more consistent optimization | Critical build speed improvement, with vendors cached after first build change | Change how CSS and JavaScript vendors are built

Dustman is coded with love by vitto @ ideato