Gulp Pipes

Opinionated, reusable Gulp pipes for handling CSS, JS, HTML, image files and more.

Installation

$ npm install --save-dev gulp-pipes

Usage Example

var gulp = require('gulp');
var pipes = require('gulp-pipes'); <<<<<<<<

gulp.task('some-task', function() {
  return gulp.src('./some-file.css')
    .pipe(pipes.css.lint())
    .pipe(pipes.css.compile())
});

IMPORTANT

All pipes take only one parameter, which is an Object containing configuration. Let's call it config object from now on. This parameter can be omitted (it is optional). All config object's properties are optional.

Jump to Point of Interest

• Banner pipes
• CSS file pipes
• Javascript file pipes
• HTML file pipes
• Image file pipes

Banner

• Method: pipes.banner(configObject);
• Adds a banner as header for files
• Comes with a default template file which takes information from your package.json

return gulp.src(...)
  .pipe(pipes.banner(configObject))

Config object properties:

| Name | Type | Description | | --- | --- | --- | | templatePath | String | Full path to template file | | variables | Object | Variables to use on the template; gets populated automatically with pkg property which is your package.json file |

Template file example (this is the default supplied one):

/* <%= pkg.name %> v<%= pkg.version %>
 * <%= pkg.homepage ? pkg.homepage + ' ' : '' %><%= pkg.license ? pkg.license + ' license' : '' %>
 * (c) <%= year %> <%= pkg.author.name || pkg.author %>
 */

All variables from above are taken from variables object.

CSS

• Supports only Stylus files.

Linter

• Method: pipes.css.lint(configObject)
• Config object parameter's (which is optional) properties:

| Name | Type | Description | | --- | --- | --- | | fail | Boolean | Fail on error |

return gulp.src('./some-file.css')
  .pipe(pipes.css.lint());

// or fail on Error
return gulp.src('./some-file.js')
  .pipe(pipes.css.lint({fail: true}));

Compiler

• Method: pipes.css.compile(configObject)
• Config object parameters:

| Name | Type | Description | | --- | --- | --- | | prod | Boolean | Compile for production | | base64 | Object | gulp-css-base64 options | | autoprefixer | Object | autoprefixer options | | extmin | Boolean | Adds '.min' to extension (use in conjunction with prod only) | | nomap | Boolean | (Dev compile only; default: true) Does not adds source maps |

autoprefixer uses this default configuration (which is overriden when specifying property in pipes.css.compile()):

{
  cascade: false,
  browsers: ['last 2 versions', '> 10%']
}

| | Development Mode | Production Mode | | --- | --- | --- | | Compile Stylus | * | * | | Auto prefixes properties for cross-browser compatibility | * | * | | Auto embeds small images with base64 encoding | * | * | | Adds sourcemaps (unless nomap = true) | * | | | Minifies | | * |

Dependencies Compiler

• Method: pipes.css.deps(configObject)
• Config object parameters:

| Name | Type | Description | | --- | --- | --- | | prod | Boolean | Compile for production | | nomap | Boolean | (Dev compile only; default: true) Does not adds source maps |

| | Development Mode | Production Mode | | --- | --- | --- | | Concats files | * | * | | Adds sourcemaps (unless nomap = true) | * | | | Loads & merges existing sourcemaps | * | | | Minifies | | * |

JS

• Uses Webpack

Linter

• Method: pipes.js.lint(configObject)
• Config object parameter's (which is optional) properties:

| Name | Type | Description | | --- | --- | --- | | fail | Boolean | Fail on error |

return gulp.src('./some-file.js')
  .pipe(pipes.js.lint())

// or fail on Error
return gulp.src('./some-file.js')
  .pipe(pipes.js.lint({fail: true}));

Compiler

• Method: pipes.js.compile(configObject)
• Config object parameters:

| Name | Type | Description | | --- | --- | --- | | prod | Boolean | Compile for production | | pack | Object | Webpack configuration | | define | Object | Object containing all properties which will be supplied to webpack.DefinePlugin; see example below | | retainPath | Boolean | makes Webpack use the same path + name as source files; by default, only name is retained | | extmin | Boolean | Adds '.min' to extension (use in conjunction with prod only) | | minify | Object | UglifyJS optional configuration |

Example for define. Please note JSON.stringify() is required.

define = {
  VERSION: JSON.stringify('1.0.1');
}

| | Development Mode | Production Mode | | --- | --- | --- | | Compiles with Webpack | * | * | | Adds sourcemaps | * | | | Minifies | | * |

If you want your compiled file to contain assets, then in your .js file to be compiled:

var content = require('raw!./template.html');

// BUT make sure you npm install raw-loader
// (Cannot include it in this package because Webpack will try to
// require it from your project folder's node_modules)

Your compiled file will contain:

var content = '<html></html>';

IMPORTANT

Also good to know that you can also use {base: 'base/path'} as option for your gulp.src().

gulp.task('some-task', function() {
  return gulp.src('path/to/script.js', {base: '/path'})
    .pipe(pipes.js.compile({
      retainPath: true
    }))
    .pipe(gulp.dest('dest/path'));
})

NOTE

Webpack configuration supplied gets merged with a default one which adds sourcemaps on development mode

You can access Webpack directly through pipes.js.webpack. For example: pipes.js.webpack.DefinePlugin.

Dependencies Compiler

• Method: pipes.js.deps(configObject)
• Config object parameters:

| Name | Type | Description | | --- | --- | --- | | prod | Boolean | Compile for production | | extmin | Boolean | Adds '.min' to extension (use in conjunction with prod only) | | minify | Object | UglifyJS optional configuration |

| | Development Mode | Production Mode | | --- | --- | --- | | Compiles with Webpack | * | * | | Adds sourcemaps | * | | | Loads & merges existing sourcemaps | * | | | Minifies | | * |

HTML

You can include other HTMLs within your .html file like this:

<!DOCTYPE html>
<html>
  <body>
  @@include('./view.html')     <<<<<<<<<<<<
  @@include('./var.html', {    <<<<<<<<<<<<
    "name": "rstoenescu",
    "age": 12345,
    "socials": {
      "fb": "facebook.com/include",
      "tw": "twitter.com/include"
    }
  })
  </body>
</html>

view.html

<h1>view</h1>

var.html

<label>@@name</label>
<label>@@age</label>
<strong>@@socials.fb</strong>
<strong>@@socials.tw</strong>

... and it gets compiled to:

<!DOCTYPE html>
<html>
  <body>
    <h1>view</h1>
    <label>rstoenescu</label>
    <label>12345</label>
    <strong>facebook.com/include</strong>
    <strong>twitter.com/include</strong>
  </body>
</html>

Linter

• Method: pipes.html.lint()
• Parameters: none

return gulp.src('./some-file.js')
  .pipe(pipes.html.lint())

Compiler

• Method: pipes.html.compile(configObject)
• Config object parameters:

| Name | Type | Description | | --- | --- | --- | | prod | Boolean | Compile for production | | include | Object | Include configuration (see below) |

| | Development Mode | Production Mode | | --- | --- | --- | | Includes HTMLs | * | * | | Minifies | | * |

Example for include object (below is the default config supplied):

prefix: '@@',
basepath: '@file'

More details on how it works can be found here.

Images

• Uses gulp-imagemin
• Method: pipes.image.optimize(configObject)

You can override any of the following default properties for the configuration object:

{
  progressive: true,
  svgoPlugins: [{removeViewBox: false}],
  use: [pngquant()]
}

Handles the following file types:

• GIF
• JPEG
• PNG
• SVG

You can feed any types of files as it will filter and optimize only image ones.

License

Copyright (c) 2015 Razvan Stoenescu

MIT License