Dustman NPM | npm.io

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