You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+90-45
Original file line number
Diff line number
Diff line change
@@ -5,107 +5,152 @@ A collection of configurable [gulp](http://gulpjs.com/) tasks we use to build fr
5
5
6
6
- Flexible configuration
7
7
- Useful logs and system alerts
8
-
- Built-in tasks: Sass with Autoprefixer, SVG sprites and JS minification
9
-
- Easy to remove or edit built-in tasks, or write your own
10
-
11
-
*Requirements:*
12
-
13
-
-[Node.js](https://nodejs.org) >= 4.0
8
+
- Use the built-in tasks (Sass with Autoprefixer, SVG sprites, and simple JS minification) or write your own
14
9
15
10
*Table of contents:*
16
11
17
12
-[Installation and usage](#installation-and-usage)
18
-
-[Configuring tasks](#configuring-tasks)
19
-
-[How to write a new task](#how-to-write-a-new-task)
13
+
-[Using tasks](#using-tasks)
14
+
-[Enable system notifications](#enable-system-notifications)
20
15
- Built-in tasks:
21
16
-[sass](doc/task-sass.md) (Sass and Autoprefixer)
22
17
-[svgsymbols](doc/task-svgsymbols.md) (SVG symbol sprites)
23
18
-[jsconcat](doc/task-jsconcat.md) (Concatenate and minify JS scripts)
19
+
-[Multiple builds per task](#multiple-builds-per-task)
20
+
-[How to write a new task](#how-to-write-a-new-task)
24
21
25
22
26
23
Installation and usage
27
24
----------------------
28
25
29
-
Install:
26
+
Requirements: [Node.js](https://nodejs.org) 4.x or above
27
+
28
+
Installing:
29
+
30
+
1.[Download a ZIP with the assets-builder scripts and config](https://github.com/gradientz/assets-builder/archive/master.zip) and unzip it in your projet directory.
31
+
3. Change the config object in `gulpfile.js`.
32
+
4. Finally, in a command prompt, go to your project dir and run:
33
+
`npm install`
34
+
35
+
Usage:
36
+
37
+
-`npm run build`: build assets once
38
+
-`npm run watch`: run in the background and build assets when source files are changed
39
+
40
+
41
+
Using tasks
42
+
-----------
43
+
44
+
To use one of the built-in tasks, you will need to do two things: 1) Configure the task and 2) Install its dependencies (if any).
45
+
46
+
### Task configuration
47
+
48
+
Configuration goes in your `gulpfile.js` and generally looks like this:
30
49
31
-
1.[Download a ZIP with the assets-builder scripts and config](https://github.com/gradientz/assets-builder/archive/master.zip),
32
-
2. move its contents to your project dir,
33
-
3. and modify the config object in `gulpfile.js` to suit your needs.
34
-
4. Finally, in a command prompt, `cd` to your project dir and run `npm install`.
The `src`, `dest` and `watch` keys are common to all tasks. Some tasks may offer other options too. For the built-in tasks, those options are documented in [the doc folder](doc).
35
61
36
-
There are two commands than you can use:
62
+
### Installing dependencies
37
63
38
-
-`npm run build` (build CSS/JS/SVG once)
39
-
-`npm run watch` (build CSS/JS/SVG when files are changed)
64
+
Task dependencies are *not* installed by default. The first time you try to run a task, with `npm run build`, you might see an error like this:
40
65
41
-
Important: if you’re using Git, don’t forget to add `node_modules` to your `.gitignore`, to avoid versioning the many files installed by npm.
66
+
```
67
+
[21:28:37] Error: missing dependencies for 'sass', 'jsconcat', 'svgsymbols'
68
+
69
+
To fix this, install missing dependencies:
70
+
71
+
npm install -D "gulp-autoprefixer@^3.1" \
72
+
"gulp-sass@^2.3" \
73
+
"gulp-uglify@^1.5" \
74
+
"gulp-svgmin@^1.2.3" \
75
+
"gulp-svg-symbols@^2.0.2"
76
+
77
+
```
42
78
79
+
You can run the provided command to install the missing dependencies. Then run `npm run build` again.
43
80
44
-
Configuring tasks
45
-
-----------------
46
81
47
-
Config objects have the following properties:
82
+
Enable system notifications
83
+
---------------------------
48
84
49
-
- Required `src`: paths or glob patterns (string or array of strings).
50
-
- Required `dest`: a single path (string).
51
-
- Optional `watch`: either the value `true` to reuse the `src` config, or a different set of paths or glob patterns (string or array of strings).
52
-
- Some tasks may offer additional options (see the next section for details).
85
+
To enable system notifications, install the `node-notifier` package:
53
86
54
-
You can make multiple builds by providing an array of config objects, instead of a single config object:
87
+
- Locally to the project: `npm install node-notifier`
88
+
- Globally on your OS: `npm install -g node-notifier`
89
+
90
+
You could also add it to the `devDependencies` (`npm install -D node-notifier`), but that’s not ideal if you want to put this code as a build step on a server.
You can also share settings between objects, using an array-like syntax where string keys are shared between configs, and number keys represent individual build configs. This is equivalent to the previous example:
117
+
You can also share settings between objects, with an array-like syntax. This is equivalent to the previous example:
If you want to write a new or different task (for example, one that transpiles ES6 code with Babel and makes a JS bundle), you can `write a task script in `assets-builder/tasks`.
89
-
90
-
This script should export a function that takes a config object and does… what you want to do. See the existing tasks for examples!
136
+
Write your own task script in `assets-builder/tasks`. This script should export a function that accepts a config object.
91
137
92
-
Here is a minimal example:
138
+
### Minimal task example
93
139
94
140
```js
95
141
/**
96
142
* assets-builder/tasks/mytask.js
97
143
*/
98
144
99
-
var gulp =require('gulp')
100
-
var __ =require('./../taskutils.js')
101
-
102
-
// Specific
103
-
var doSomething =require('gulp-do-something')
145
+
constgulp=require('gulp')
146
+
consttools=require('../tasktools.js')
147
+
constdoSomething=require('gulp-do-something')
104
148
105
149
module.exports=functionmytask(conf) {
106
150
returngulp.src(conf.src) // take some files
107
-
.pipe(__.logerrors())// tell gulp to show errors and continue
151
+
.pipe(tools.errors()) // tell gulp to show errors and continue
108
152
.pipe(doSomething()) // use a gulp plugin to transform content
153
+
.pipe(tools.size(conf.dest)) // log resulting file path/names and size
109
154
.pipe(gulp.dest(conf.dest)) // write resulting files to destination
0 commit comments