gulp-pipes

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