npm package: @simpleweb/gulp
Description: Commonly used Gulp tasks to get you off the ground faster
Author: Benjamin Reid
Latest version: 2.0.2

# gulp
Commonly used Gulp tasks to get you off the ground faster

## What does it do?

`@simpleweb/gulp` abstracts some of the most commonly used tasks we use across
projects, like compiling Sass and ES6. It's aim is to take away the menial
things you have to do each time to get these working.

It does this by giving you a set of [tasks](#tasks), these simply return Gulp streams.
There's no magic going on below the surface.


## Quick start

- [Styles](#styles) - Compiles **Sass to CSS** for you, it'll also apply
**Autoprefixer** and include any **Bower** dependencies.
- [Sass](#sass) - Simply compiles **Sass to CSS**.
- [Scripts](#scripts) - Compiles **ES6 to ES5** compliant JavaScript and can
include any **Bower** dependencies.
- [ES6](#es6) - Simply compiles **ES6 to ES5** compliant JavaScript.

## Super quick start ⚡

If you're looking to get off the ground even faster and happy with some default
behaviours being set, this is for you.

Just specify the directory of your sources files and your destinations and
you'll get access to the following `gulp` tasks.

- `scripts` - Compiles **ES6 to ES5** and loads in Bower dependencies.
- `styles` - Compiles **Sass to CSS**, runs **Autoprefixer** and loads in
**Bower** dependencies.
- `watch` - Automatically watches the directories of the source files in the
config. e.g. if `scripts/main.js` is the source file, `scripts/**/*.js` will
be watched.

> When running any of these tasks, a `--production` flag can be used to minify
the compiled CSS/JavaScript.

```js
var gulp = require('gulp');

require('@simpleweb/gulp').auto(gulp, {
  styles: {
    src: './styles.scss',
    dest: './dist'
  },
  scripts: {
    src: './main.js',
    dest: './dist'
  },
});
```

## Installation

Install the module from NPM by running the following.

```bash
$ npm install @simpleweb/gulp --save-dev
```

Then require it in your `gulpfile.js`.

```js
var tasks = require('@simpleweb/gulp').tasks;
```

## Tasks

### Styles

Compiles Sass, _can_ concatenate Bower dependencies and
_can_ pass everything through Autoprefixer.

##### Example

```js
gulp.task('styles', function() {
  return tasks.styles({
      src: './styles/styles.scss',
      bower: true,
      autoprefixer: true
    })
    .pipe(gulp.dest('./tmp'))
  ;
});
```

##### Parameters

|argument|type|default|description|
|---|---|---|---|
| `src` | `String` | | Path to the main Sass file |
| `bower` | `Boolean` | `false` | Whether to load in Bower dependencies. If `true`, `bower.json` must exist along with it's components folder |
| `autoprefixer` | `Object`/`Boolean` | `false` | You can use all `autoprefixer` [options](https://github.com/postcss/autoprefixer#options) or pass `true` to run with default options |

##### Flags

A `production` flag can be passed to minify the CSS for production.

```
$ gulp styles --production
```

### Sass

Compiles Sass into CSS using `gulp-sass`.

##### Example

```js
gulp.task('sass', function() {
  return tasks.sass('./main.scss')
    .pipe(gulp.dest('./css'));
});
```

##### Parameters

|argument|type|default|description|
|---|---|---|---|
| `src` | `String` | | Path to the main Sass file |
| `options` | `Object` | `{}` | You can use all the `node-sass` [options](https://github.com/sass/node-sass#options) |

### ES6

Compiles ES6 into JavaScript that's ES5 compliant. ES3 transforms are
applied to it as well, so it will work with IE8. However, you will still need to
use the [shim and sham](https://github.com/es-shims/es5-shim) with it.

##### Example

```js
gulp.task('es6', function() {
  return tasks.es6('./main.js')
    .pipe(gulp.dest('./js'))
  ;
});
```

##### Parameters

|argument|type|default|description|
|---|---|---|---|
| `src` | `String` | | Path to the main ES6 file |

### Scripts

Compiles ES6 into JavaScript that's ES5 compliant and _can_ bundle in your
Bower dependencies.

##### Example

```js
gulp.task('scripts', function() {
  return tasks.scripts({
      src: './main.js',
      bower: true
    })
    .pipe(gulp.dest('./js'))
  ;
});
```

##### Parameters

|argument|type|default|description|
|---|---|---|---|
| `src` | `String` | | Path to the main ES6 file |
| `bower` | `Boolean` | `false` | Whether to load in Bower dependencies. If `true`, `bower.json` must exist along with it's components folder |

##### Flags

A `production` flag can be passed to minify the CSS for production.

```
$ gulp scripts --production
```

## Development

### Setup

You can work on this locally without having to continuously publish to NPM.
After cloning the repo down, `cd` into the directory and run `npm link`. This
will create a symbolic in your global modules folder.

To install it in a project and test out, run `npm link @simpleweb/gulp`. You can
then require it like you usually would. This is the equivalent of running
`npm install @simpleweb/gulp` except it uses the symbolic link in your global
modules folder.

### Adding a task

To create a new task think of a clear and descriptive name and create a file
for it in the `tasks` directory.

```bash
$ touch tasks/hello-world.js
```

In the file that was just created, export the main function for that task.

```js
module.exports = function() {
  console.log('Hello world');
};
```

At the top of `index.js`, `require` the task and give it a clear constant name.

```js
const hello_world = require('./tasks/hello-world');
```

Finally, add the module to the `exports` line.

```js
module.exports = { sass, hello_world };
```