1 | # [gulp](https://github.com/gulpjs/gulp)-useref [![Build Status](https://travis-ci.org/jonkemp/gulp-useref.svg?branch=master)](https://travis-ci.org/jonkemp/gulp-useref) [![Coverage Status](https://coveralls.io/repos/jonkemp/gulp-useref/badge.svg?branch=master&service=github)](https://coveralls.io/github/jonkemp/gulp-useref?branch=master)
|
2 |
|
3 | [![NPM](https://nodei.co/npm/gulp-useref.png?downloads=true)](https://nodei.co/npm/gulp-useref/)
|
4 |
|
5 | > Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets with [useref](https://github.com/jonkemp/useref)
|
6 |
|
7 | Inspired by the grunt plugin [grunt-useref](https://github.com/pajtai/grunt-useref). It can handle file concatenation but not minification. Files are then passed down the stream. For minification of assets or other modifications, use [gulp-if](https://github.com/robrich/gulp-if) to conditionally handle specific types of assets.
|
8 |
|
9 |
|
10 | ## What's new in 3.0?
|
11 |
|
12 | Changes under the hood have made the code more efficient and simplified the API. Since the API has changed, please observe the usage examples below.
|
13 |
|
14 | If you get errors like
|
15 |
|
16 | TypeError: useref.assets is not a function
|
17 |
|
18 | or
|
19 |
|
20 | TypeError: $.useref.assets is not a function
|
21 |
|
22 | please read the Migration Notes below.
|
23 |
|
24 | ## Install
|
25 |
|
26 | Install with [npm](https://npmjs.org/package/gulp-useref)
|
27 |
|
28 | ```
|
29 | npm install --save-dev gulp-useref
|
30 | ```
|
31 |
|
32 |
|
33 | ## Usage
|
34 |
|
35 | The following example will parse the build blocks in the HTML, replace them and pass those files through. Assets inside the build blocks will be concatenated and passed through in a stream as well.
|
36 |
|
37 | ```js
|
38 | var gulp = require('gulp'),
|
39 | useref = require('gulp-useref');
|
40 |
|
41 | gulp.task('default', function () {
|
42 | return gulp.src('app/*.html')
|
43 | .pipe(useref())
|
44 | .pipe(gulp.dest('dist'));
|
45 | });
|
46 | ```
|
47 |
|
48 | With options:
|
49 |
|
50 | ```js
|
51 | var gulp = require('gulp'),
|
52 | useref = require('gulp-useref');
|
53 |
|
54 | gulp.task('default', function () {
|
55 | return gulp.src('app/*.html')
|
56 | .pipe(useref({ searchPath: '.tmp' }))
|
57 | .pipe(gulp.dest('dist'));
|
58 | });
|
59 | ```
|
60 |
|
61 | If you want to minify your assets or perform some other modification, you can use [gulp-if](https://github.com/robrich/gulp-if) to conditionally handle specific types of assets.
|
62 |
|
63 | ```js
|
64 | var gulp = require('gulp'),
|
65 | useref = require('gulp-useref'),
|
66 | gulpif = require('gulp-if'),
|
67 | uglify = require('gulp-uglify'),
|
68 | minifyCss = require('gulp-clean-css');
|
69 |
|
70 | gulp.task('html', function () {
|
71 | return gulp.src('app/*.html')
|
72 | .pipe(useref())
|
73 | .pipe(gulpif('*.js', uglify()))
|
74 | .pipe(gulpif('*.css', minifyCss()))
|
75 | .pipe(gulp.dest('dist'));
|
76 | });
|
77 | ```
|
78 |
|
79 | Blocks are expressed as:
|
80 |
|
81 | ```html
|
82 | <!-- build:<type>(alternate search path) <path> <parameters> -->
|
83 | ... HTML Markup, list of script / link tags.
|
84 | <!-- endbuild -->
|
85 | ```
|
86 |
|
87 | - **type**: either `js`, `css` or `remove`; `remove` will remove the build block entirely without generating a file
|
88 | - **alternate search path**: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that. The path can also contain a sequence of paths processed from right to left, using JSON brace array notation e.g `<!-- build:js({path1,path2}) js/lib.js -->`.
|
89 | - **path**: the file path of the optimized file, the target output
|
90 | - **parameters**: extra parameters that should be added to the tag
|
91 |
|
92 | An example of this in completed form can be seen below:
|
93 |
|
94 | ```html
|
95 | <html>
|
96 | <head>
|
97 | <!-- build:css css/combined.css -->
|
98 | <link href="css/one.css" rel="stylesheet">
|
99 | <link href="css/two.css" rel="stylesheet">
|
100 | <!-- endbuild -->
|
101 | </head>
|
102 | <body>
|
103 | <!-- build:js scripts/combined.js -->
|
104 | <script type="text/javascript" src="scripts/one.js"></script>
|
105 | <script type="text/javascript" src="scripts/two.js"></script>
|
106 | <!-- endbuild -->
|
107 | </body>
|
108 | </html>
|
109 | ```
|
110 |
|
111 | The resulting HTML would be:
|
112 |
|
113 | ```html
|
114 | <html>
|
115 | <head>
|
116 | <link rel="stylesheet" href="css/combined.css"/>
|
117 | </head>
|
118 | <body>
|
119 | <script src="scripts/combined.js"></script>
|
120 | </body>
|
121 | </html>
|
122 | ```
|
123 |
|
124 | See [useref](https://github.com/jonkemp/useref) for more information.
|
125 |
|
126 | ## API
|
127 |
|
128 | ### useref(options [, transformStream1 [, transformStream2 [, ... ]]])
|
129 |
|
130 | Returns a stream with the asset replaced resulting HTML files as well as the concatenated asset files from the build blocks inside the HTML. Supports all options from [useref](https://github.com/jonkemp/useref).
|
131 |
|
132 | ### Transform Streams
|
133 |
|
134 | Type: `Stream`
|
135 | Default: `none`
|
136 |
|
137 | Transform assets before concat. For example, to integrate source maps:
|
138 |
|
139 | ```js
|
140 | var gulp = require('gulp'),
|
141 | sourcemaps = require('gulp-sourcemaps'),
|
142 | useref = require('gulp-useref'),
|
143 | lazypipe = require('lazypipe');
|
144 |
|
145 | gulp.task('default', function () {
|
146 | return gulp.src('index.html')
|
147 | .pipe(useref({}, lazypipe().pipe(sourcemaps.init, { loadMaps: true })))
|
148 | .pipe(sourcemaps.write('maps'))
|
149 | .pipe(gulp.dest('dist'));
|
150 | });
|
151 | ```
|
152 |
|
153 | ### Options
|
154 |
|
155 | #### options.searchPath
|
156 |
|
157 | Type: `String` or `Array`
|
158 | Default: `none`
|
159 |
|
160 | Specify the location to search for asset files, relative to the current working directory. Can be a string or array of strings.
|
161 |
|
162 | #### options.base
|
163 |
|
164 | Type: `String`
|
165 | Default: `process.cwd()`
|
166 |
|
167 | Specify the output folder relative to the cwd.
|
168 |
|
169 | #### options.noAssets
|
170 |
|
171 | Type: `Boolean`
|
172 | Default: `false`
|
173 |
|
174 | Skip assets and only process the HTML files.
|
175 |
|
176 | #### options.noconcat
|
177 |
|
178 | Type: `Boolean`
|
179 | Default: `false`
|
180 |
|
181 | Skip concatenation and add all assets to the stream instead.
|
182 |
|
183 | #### options.newLine
|
184 |
|
185 | Type: `String`
|
186 | Default: `none`
|
187 |
|
188 | Add a string that should separate the concatenated files.
|
189 |
|
190 | #### options.additionalStreams
|
191 |
|
192 | Type: `Array<Stream>`
|
193 | Default: `none`
|
194 |
|
195 | Use additional streams as sources of assets. Useful for combining gulp-useref with preprocessing tools. For example, to use with TypeScript:
|
196 |
|
197 | ```javascript
|
198 | var ts = require('gulp-typescript');
|
199 |
|
200 | // create stream of virtual files
|
201 | var tsStream = gulp.src('src/**/*.ts')
|
202 | .pipe(ts());
|
203 |
|
204 | gulp.task('default', function () {
|
205 | // use gulp-useref normally
|
206 | return gulp.src('src/index.html')
|
207 | .pipe(useref({ additionalStreams: [tsStream] }))
|
208 | .pipe(gulp.dest('dist'));
|
209 | });
|
210 | ```
|
211 |
|
212 | #### options.transformPath
|
213 |
|
214 | Type: `Function`
|
215 | Default: `none`
|
216 |
|
217 | Add a transformPath function in case the path needs to be modified before search happens.
|
218 |
|
219 | ```js
|
220 | var gulp = require('gulp'),
|
221 | useref = require('gulp-useref');
|
222 |
|
223 | gulp.task('default', function () {
|
224 | return gulp.src('app/*.html')
|
225 | .pipe(useref({
|
226 | transformPath: function(filePath) {
|
227 | return filePath.replace('/rootpath','')
|
228 | }
|
229 | }))
|
230 | .pipe(gulp.dest('dist'));
|
231 | });
|
232 | ```
|
233 |
|
234 | ## Migration from v2 API
|
235 |
|
236 | If you upgrade gulp-useref from v2 without changing your gulpfile,
|
237 | you will get errors like this:
|
238 |
|
239 | TypeError: $.useref.assets is not a function
|
240 |
|
241 | or
|
242 |
|
243 | TypeError: useref.assets is not a function
|
244 |
|
245 | For a simple configuration, you can replace this V2 code:
|
246 |
|
247 | ```js
|
248 | var gulp = require('gulp'),
|
249 | useref = require('gulp-useref');
|
250 |
|
251 | gulp.task('default', function () {
|
252 | var assets = useref.assets();
|
253 |
|
254 | return gulp.src('app/*.html')
|
255 | .pipe(assets)
|
256 | .pipe(assets.restore())
|
257 | .pipe(useref())
|
258 | .pipe(gulp.dest('dist'));
|
259 | });
|
260 | ```
|
261 |
|
262 | with this V3 code:
|
263 |
|
264 | ```js
|
265 | var gulp = require('gulp'),
|
266 | useref = require('gulp-useref');
|
267 |
|
268 | gulp.task('default', function () {
|
269 | return gulp.src('app/*.html')
|
270 | .pipe(useref())
|
271 | .pipe(gulp.dest('dist'));
|
272 | });
|
273 | ```
|
274 |
|
275 | If you were previously using useref in a multi-stage pipe,
|
276 | you may need to rewrite the pipe, since the simplified V3 API
|
277 | may not allow for its previous usage.
|
278 |
|
279 | If the gulpfile you are using came from a generator, (for example,
|
280 | in JohnPapa's excellent "opinionated" HotTowel generator), it may
|
281 | be more practical to go back to that generator project to see
|
282 | whether they have upgraded to the V3 gulp-useref API, rather than
|
283 | trying to understand their pipe.
|
284 |
|
285 |
|
286 | ## Notes
|
287 |
|
288 | * [ClosureCompiler.js](https://github.com/dcodeIO/ClosureCompiler.js) doesn't support Buffers, which means if you want to use [gulp-closure-compiler](https://github.com/sindresorhus/gulp-closure-compiler) you'll have to first write out the `combined.js` to disk. See [this](https://github.com/dcodeIO/ClosureCompiler.js/issues/11) for more information.
|
289 |
|
290 |
|
291 | ## Contributing
|
292 |
|
293 | See the [CONTRIBUTING Guidelines](https://github.com/jonkemp/gulp-useref/blob/master/CONTRIBUTING.md)
|
294 |
|
295 |
|
296 | ## License
|
297 |
|
298 | MIT © [Jonathan Kemp](http://jonkemp.com)
|