1 | # gulp-inject
|
2 |
|
3 | ---
|
4 | ## HELP WANTED
|
5 |
|
6 |
|
7 | ### Contributors are welcomed!
|
8 |
|
9 | **I don't have enough time to maintain this plugin as I would want to, so I'm looking for people who want to help out and be contributors/repository admins.**
|
10 |
|
11 |
|
12 | #### Interested?
|
13 | **Contact me! See `package.json` for contact information.**
|
14 |
|
15 | ---
|
16 |
|
17 | [![NPM version][npm-image]][npm-url] [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![Build Status][travis-image]][travis-url] [![XO code style][codestyle-image]][codestyle-url] [![Dependency Status][depstat-image]][depstat-url]
|
18 |
|
19 | > A stylesheet, javascript and webcomponent reference injection plugin for [gulp](https://github.com/wearefractal/gulp). No more manual editing of your index.html!
|
20 |
|
21 | # Contents
|
22 |
|
23 |
|
24 |
|
25 | - [Introduction](#introduction)
|
26 | - [Installation](#installation)
|
27 | - [Basic usage](#basic-usage)
|
28 | - [More examples](#more-examples)
|
29 | - [Injecting files relative to target files](#injecting-files-relative-to-target-files)
|
30 | - [Injecting files from multiple source streams](#injecting-files-from-multiple-source-streams)
|
31 | - [Multiple sources when order is important](#multiple-sources-when-order-is-important)
|
32 | - [Injecting some files into `<head>` and some into `<body>`](#injecting-some-files-into-head-and-some-into-body)
|
33 | - [Method 1: Use `gulp-inject`'s `starttag` option.](#method-1-use-gulp-injects-starttag-option)
|
34 | - [Method 2: Use `gulp-inject`'s `name` option.](#method-2-use-gulp-injects-name-option)
|
35 | - [Injecting all files for development](#injecting-all-files-for-development)
|
36 | - [Injecting AngularJS scripts for development](#injecting-angularjs-scripts-for-development)
|
37 | - [Injecting into a json-file](#injecting-into-a-json-file)
|
38 | - [Injecting with custom `transform` function with default fallback](#injecting-with-custom-transform-function-with-default-fallback)
|
39 | - [Injecting dist files into bower.json's main section](#injecting-dist-files-into-bowerjsons-main-section)
|
40 | - [Injecting all javascript files into a karma config file](#injecting-all-javascript-files-into-a-karma-config-file)
|
41 | - [Injecting files contents](#injecting-files-contents)
|
42 | - [Injecting files contents based on file path](#injecting-files-contents-based-on-file-path)
|
43 | - [API](#api)
|
44 | - [inject(sources, options)](#injectsources-options)
|
45 | - [Options](#options)
|
46 | - [options.ignorePath](#optionsignorepath)
|
47 | - [options.relative](#optionsrelative)
|
48 | - [options.addPrefix](#optionsaddprefix)
|
49 | - [options.addSuffix](#optionsaddsuffix)
|
50 | - [options.addRootSlash](#optionsaddrootslash)
|
51 | - [options.name](#optionsname)
|
52 | - [options.removeTags](#optionsremovetags)
|
53 | - [options.empty](#optionsempty)
|
54 | - [options.starttag](#optionsstarttag)
|
55 | - [options.endtag](#optionsendtag)
|
56 | - [options.transform](#optionstransform)
|
57 | - [options.selfClosingTag](#optionsselfclosingtag)
|
58 | - [~~options.templateString~~](#optionstemplatestring)
|
59 | - [~~options.sort~~](#optionssort)
|
60 | - [inject.transform](#injecttransform)
|
61 | - [License](#license)
|
62 |
|
63 |
|
64 |
|
65 | ## Introduction
|
66 |
|
67 | `gulp-inject` takes a stream of source files, transforms each file to a string and injects each transformed string into placeholders in the target stream files. See [Basic usage](#basic-usage) and [More examples](#more-examples) below.
|
68 |
|
69 | Default [transforms](#optionstransform) and [placeholders](#optionsstarttag) exists for injecting files into `html`, `jade`, `pug`, `jsx` , `less`, `slm`, `haml` and `sass` / `scss` files.
|
70 |
|
71 | ## Installation
|
72 |
|
73 | Install `gulp-inject` as a development dependency:
|
74 |
|
75 | ```shell
|
76 | npm install --save-dev gulp-inject
|
77 | ```
|
78 |
|
79 | ## Basic usage
|
80 |
|
81 | **The target file `src/index.html`:**
|
82 |
|
83 | Each pair of comments are the injection placeholders (aka. tags, see [`options.starttag`](#optionsstarttag) and [`options.endtag`](#optionsendtag)).
|
84 |
|
85 | ```html
|
86 | <!DOCTYPE html>
|
87 | <html>
|
88 | <head>
|
89 | <title>My index</title>
|
90 | <!-- inject:css -->
|
91 | <!-- endinject -->
|
92 | </head>
|
93 | <body>
|
94 |
|
95 | <!-- inject:js -->
|
96 | <!-- endinject -->
|
97 | </body>
|
98 | </html>
|
99 | ```
|
100 |
|
101 | **The `gulpfile.js`:**
|
102 |
|
103 | ```javascript
|
104 | var gulp = require('gulp');
|
105 | var inject = require('gulp-inject');
|
106 |
|
107 | gulp.task('index', function () {
|
108 | var target = gulp.src('./src/index.html');
|
109 | // It's not necessary to read the files (will speed up things), we're only after their paths:
|
110 | var sources = gulp.src(['./src/**/*.js', './src/**/*.css'], {read: false});
|
111 |
|
112 | return target.pipe(inject(sources))
|
113 | .pipe(gulp.dest('./src'));
|
114 | });
|
115 | ```
|
116 |
|
117 | **`src/index.html` after running `gulp index`:**
|
118 |
|
119 | ```html
|
120 | <!DOCTYPE html>
|
121 | <html>
|
122 | <head>
|
123 | <title>My index</title>
|
124 | <!-- inject:css -->
|
125 | <link rel="stylesheet" href="/src/style1.css">
|
126 | <link rel="stylesheet" href="/src/style2.css">
|
127 | <!-- endinject -->
|
128 | </head>
|
129 | <body>
|
130 |
|
131 | <!-- inject:js -->
|
132 | <script src="/src/lib1.js"></script>
|
133 | <script src="/src/lib2.js"></script>
|
134 | <!-- endinject -->
|
135 | </body>
|
136 | </html>
|
137 | ```
|
138 |
|
139 | ## More examples
|
140 |
|
141 | ### Injecting files relative to target files
|
142 |
|
143 | By default the injected file paths are relative to each source file's `cwd` (see [`options.ignorePath`](#optionsignorepath)). If `options.relative` is set to `true` each injected path will be relative to each target file's directory instead.
|
144 |
|
145 | **Project structure:**
|
146 |
|
147 | ```
|
148 | └── src
|
149 | ├── module
|
150 | │ ├── module.js
|
151 | │ └── module.html
|
152 | └── app
|
153 | ├── main.js
|
154 | └── index.html
|
155 | ```
|
156 |
|
157 | **`src/app/index.html`:**
|
158 |
|
159 | ```html
|
160 | <!DOCTYPE html>
|
161 | <html>
|
162 | <head>
|
163 | <title>My Index</title>
|
164 | </head>
|
165 | <body>
|
166 | <h1>Home</h1>
|
167 | <!-- inject:js -->
|
168 | <!-- endinject -->
|
169 | </body>
|
170 | </html>
|
171 | ```
|
172 |
|
173 | **`src/module/module.html`:**
|
174 |
|
175 | ```html
|
176 | <!DOCTYPE html>
|
177 | <html>
|
178 | <head>
|
179 | <title>Module</title>
|
180 | </head>
|
181 | <body>
|
182 | <h1>Module</h1>
|
183 | <!-- inject:js -->
|
184 | <!-- endinject -->
|
185 | </body>
|
186 | </html>
|
187 | ```
|
188 |
|
189 | **`gulpfile.js`:**
|
190 |
|
191 | ```javascript
|
192 | var inject = require('gulp-inject');
|
193 |
|
194 | gulp.src('./src/**/*.html')
|
195 | .pipe(inject(gulp.src('./src/**/*.js', {read: false}), {relative: true}))
|
196 | .pipe(gulp.dest('./src'));
|
197 | ```
|
198 |
|
199 | **Resulting `src/app/index.html`:**
|
200 |
|
201 | ```html
|
202 | <!DOCTYPE html>
|
203 | <html>
|
204 | <head>
|
205 | <title>My Index</title>
|
206 | </head>
|
207 | <body>
|
208 | <h1>Home</h1>
|
209 | <!-- inject:js -->
|
210 | <script src="main.js"></script>
|
211 | <script src="../module/module.js"></script>
|
212 | <!-- endinject -->
|
213 | </body>
|
214 | </html>
|
215 | ```
|
216 |
|
217 | **Resulting `src/module/module.html`:**
|
218 |
|
219 | ```html
|
220 | <!DOCTYPE html>
|
221 | <html>
|
222 | <head>
|
223 | <title>Module</title>
|
224 | </head>
|
225 | <body>
|
226 | <h1>Home</h1>
|
227 | <!-- inject:js -->
|
228 | <script src="../app/main.js"></script>
|
229 | <script src="module.js"></script>
|
230 | <!-- endinject -->
|
231 | </body>
|
232 | </html>
|
233 | ```
|
234 |
|
235 | ### Injecting files from multiple source streams
|
236 |
|
237 | This example demonstrates how to inject files from multiple different streams into the same injection placeholder.
|
238 |
|
239 | Install [`event-stream`](https://www.npmjs.org/package/event-stream) with: `npm install --save-dev event-stream` and use its [`merge`](https://github.com/dominictarr/event-stream#merge-stream1streamn) function.
|
240 |
|
241 | **Code:**
|
242 |
|
243 | ```javascript
|
244 | var es = require('event-stream'),
|
245 | inject = require('gulp-inject'),
|
246 | concat = require('gulp-concat'),
|
247 | uglify = require('gulp-uglify');
|
248 |
|
249 | // Concatenate vendor scripts
|
250 | var vendorStream = gulp.src(['./src/vendors/*.js'])
|
251 | .pipe(concat('vendors.js'))
|
252 | .pipe(gulp.dest('./dist'));
|
253 |
|
254 | // Concatenate AND minify app sources
|
255 | var appStream = gulp.src(['./src/app/*.js'])
|
256 | .pipe(concat('app.js'))
|
257 | .pipe(uglify())
|
258 | .pipe(gulp.dest('./dist'));
|
259 |
|
260 | gulp.src('./src/index.html')
|
261 | .pipe(inject(es.merge(vendorStream, appStream)))
|
262 | .pipe(gulp.dest('./dist'));
|
263 | ```
|
264 |
|
265 | #### Multiple sources when order is important
|
266 |
|
267 | Use [`stream-series`](https://github.com/rschmukler/stream-series).
|
268 |
|
269 | **Code:**
|
270 |
|
271 | ```javascript
|
272 | var series = require('stream-series'),
|
273 | inject = require('gulp-inject');
|
274 |
|
275 | var vendorStream = gulp.src(['./src/vendors/*.js'], {read: false});
|
276 |
|
277 | var appStream = gulp.src(['./src/app/*.js'], {read: false});
|
278 |
|
279 | gulp.src('./src/index.html')
|
280 | .pipe(inject(series(vendorStream, appStream))) // This will always inject vendor files before app files
|
281 | .pipe(gulp.dest('./dist'));
|
282 | ```
|
283 |
|
284 | ### Injecting some files into `<head>` and some into `<body>`
|
285 |
|
286 | #### Method 1: Use `gulp-inject`'s `starttag` option.
|
287 |
|
288 | **`gulpfile.js`:**
|
289 |
|
290 | ```javascript
|
291 | var inject = require('gulp-inject');
|
292 |
|
293 | gulp.src('./src/index.html')
|
294 | .pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {starttag: '<!-- inject:head:{{ext}} -->'}))
|
295 | .pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
|
296 | .pipe(gulp.dest('./dist'));
|
297 | ```
|
298 |
|
299 | **And in your `./src/index.html`:**
|
300 |
|
301 | ```html
|
302 | <!DOCTYPE html>
|
303 | <html>
|
304 | <head>
|
305 | <title>My index</title>
|
306 | <!-- inject:head:js -->
|
307 | <!-- only importantFile.js will be injected here -->
|
308 | <!-- endinject -->
|
309 | </head>
|
310 | <body>
|
311 |
|
312 | <!-- inject:js -->
|
313 | <!-- the rest of the *.js files will be injected here -->
|
314 | <!-- endinject -->
|
315 | </body>
|
316 | </html>
|
317 | ```
|
318 |
|
319 | #### Method 2: Use `gulp-inject`'s `name` option.
|
320 |
|
321 | **`gulpfile.js`:**
|
322 |
|
323 | ```javascript
|
324 | var inject = require('gulp-inject');
|
325 |
|
326 | gulp.src('./src/index.html')
|
327 | .pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {name: 'head'}))
|
328 | .pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
|
329 | .pipe(gulp.dest('./dist'));
|
330 | ```
|
331 |
|
332 | **And in your `./src/index.html`:**
|
333 |
|
334 | ```html
|
335 | <!DOCTYPE html>
|
336 | <html>
|
337 | <head>
|
338 | <title>My index</title>
|
339 | <!-- head:js -->
|
340 | <!-- only importantFile.js will be injected here -->
|
341 | <!-- endinject -->
|
342 | </head>
|
343 | <body>
|
344 |
|
345 | <!-- inject:js -->
|
346 | <!-- the rest of the *.js files will be injected here -->
|
347 | <!-- endinject -->
|
348 | </body>
|
349 | </html>
|
350 | ```
|
351 |
|
352 |
|
353 | ### Injecting all files for development
|
354 |
|
355 | If you use [Bower](http://bower.io/) for frontend dependencies I recommend using [`main-bower-files`](https://www.npmjs.org/package/main-bower-files) and injecting them as well.
|
356 |
|
357 | **`gulpfile.js`:**
|
358 |
|
359 | ```javascript
|
360 | var bowerFiles = require('main-bower-files'),
|
361 | inject = require('gulp-inject'),
|
362 | stylus = require('gulp-stylus'),
|
363 | es = require('event-stream');
|
364 |
|
365 | var cssFiles = gulp.src('./src/**/*.styl')
|
366 | .pipe(stylus())
|
367 | .pipe(gulp.dest('./build'));
|
368 |
|
369 | gulp.src('./src/index.html')
|
370 | .pipe(inject(gulp.src(bowerFiles(), {read: false}), {name: 'bower'}))
|
371 | .pipe(inject(es.merge(
|
372 | cssFiles,
|
373 | gulp.src('./src/app/**/*.js', {read: false})
|
374 | )))
|
375 | .pipe(gulp.dest('./build'));
|
376 | ```
|
377 |
|
378 | **`src/index.html`:**
|
379 |
|
380 | ```html
|
381 | <!DOCTYPE html>
|
382 | <html>
|
383 | <head>
|
384 | <title>My index</title>
|
385 | <!-- bower:css -->
|
386 | <!-- bower installed css files will go here... -->
|
387 | <!-- endinject -->
|
388 | <!-- inject:css -->
|
389 | <!-- built css files will go here... -->
|
390 | <!-- endinject -->
|
391 | </head>
|
392 | <body>
|
393 |
|
394 | <!-- bower:js -->
|
395 | <!-- bower installed scripts will go here... -->
|
396 | <!-- endinject -->
|
397 | <!-- inject:js -->
|
398 | <!-- app scripts will go here... -->
|
399 | <!-- endinject -->
|
400 | </body>
|
401 | </html>
|
402 | ```
|
403 |
|
404 | **Note** remember to mount `./bower_components`, `./build` and `./src/app` as static resources in your server to make this work.
|
405 |
|
406 | ### Injecting AngularJS scripts for development
|
407 |
|
408 | If you're writing an AngularJS application and follow [Google's Angular APP Structure Recommendations](https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub), which I think you should, it's important that the script files are injected in the correct order to avoid module instantiation problems like `Uncaught Error: [$injector:modulerr]`.
|
409 |
|
410 | To do this you can use [`gulp-angular-filesort`](https://www.npmjs.org/package/gulp-angular-filesort) together with `gulp-inject` like so:
|
411 |
|
412 | ```javascript
|
413 | var angularFilesort = require('gulp-angular-filesort'),
|
414 | inject = require('gulp-inject');
|
415 |
|
416 | gulp.src('./src/index.html')
|
417 | .pipe(inject(
|
418 | gulp.src('./src/app/**/*.js') // gulp-angular-filesort depends on file contents, so don't use {read: false} here
|
419 | .pipe(angularFilesort())
|
420 | ))
|
421 | .pipe(gulp.dest('./build'));
|
422 | ```
|
423 |
|
424 | ### Injecting into a json-file
|
425 |
|
426 | You can customize `gulp-inject` further by using the `transform` function option, e.g. by injecting files into a json-file.
|
427 |
|
428 | **Code:**
|
429 |
|
430 | ```javascript
|
431 | gulp.src('./files.json')
|
432 | .pipe(inject(gulp.src(['./src/*.js', './src/*.css', './src/*.html'], {read: false}), {
|
433 | starttag: '"{{ext}}": [',
|
434 | endtag: ']',
|
435 | transform: function (filepath, file, i, length) {
|
436 | return ' "' + filepath + '"' + (i + 1 < length ? ',' : '');
|
437 | }
|
438 | }))
|
439 | .pipe(gulp.dest('./'));
|
440 | ```
|
441 |
|
442 | Initial contents of `files.json`:
|
443 |
|
444 | ```json
|
445 | {
|
446 | "js": [
|
447 | ],
|
448 | "css": [
|
449 | ],
|
450 | "html": [
|
451 | ]
|
452 | }
|
453 | ```
|
454 |
|
455 | ### Injecting with custom `transform` function with default fallback
|
456 |
|
457 | The [default `transform`](#injecttransform) function is available to use e.g. as a default fallback.
|
458 |
|
459 | Used here to inject Word documents as `<a>` tags below:
|
460 |
|
461 | **`index.html`:**
|
462 |
|
463 | ```html
|
464 | <!DOCTYPE html>
|
465 | <html>
|
466 | <head>
|
467 | <title>My documents</title>
|
468 | </head>
|
469 | <body>
|
470 | <h1>Documents</h1>
|
471 | <ul>
|
472 | <!-- inject:docx -->
|
473 | <!-- endinject -->
|
474 | </ul>
|
475 | <!-- inject:js -->
|
476 | <!-- endinject -->
|
477 | </body>
|
478 | </html>
|
479 | ```
|
480 |
|
481 | **`gulpfile.js`:**
|
482 |
|
483 | ```javascript
|
484 | var inject = require('gulp-inject');
|
485 |
|
486 | gulp.src('./index.html')
|
487 | .pipe(inject(
|
488 | gulp.src(['./*.js', './docs/*.docx'], {read: false}), {
|
489 | transform: function (filepath) {
|
490 | if (filepath.slice(-5) === '.docx') {
|
491 | return '<li><a href="' + filepath + '">' + filepath + '</a></li>';
|
492 | }
|
493 | // Use the default transform as fallback:
|
494 | return inject.transform.apply(inject.transform, arguments);
|
495 | }
|
496 | }
|
497 | ))
|
498 | .pipe(gulp.dest('./'));
|
499 | ```
|
500 |
|
501 | **Resulting `index.html`:**
|
502 |
|
503 | ```html
|
504 | <!DOCTYPE html>
|
505 | <html>
|
506 | <head>
|
507 | <title>My documents</title>
|
508 | </head>
|
509 | <body>
|
510 | <h1>Documents</h1>
|
511 | <ul>
|
512 | <!-- inject:docx -->
|
513 | <li><a href="/docs/document1.docx"></a></li>
|
514 | <li><a href="/docs/document2.docx"></a></li>
|
515 | <!-- endinject -->
|
516 | </ul>
|
517 | <!-- inject:js -->
|
518 | <script src="/lib1.js"></script>
|
519 | <script src="/lib2.js"></script>
|
520 | <!-- endinject -->
|
521 | </body>
|
522 | </html>
|
523 | ```
|
524 |
|
525 | ### Injecting dist files into bower.json's main section
|
526 |
|
527 | **Code:**
|
528 |
|
529 | ```javascript
|
530 | gulp.src('./bower.json')
|
531 | .pipe(inject(gulp.src(['./dist/app.min.js', './dist/app.min.css'], {read: false}), {
|
532 | starttag: '"main": [',
|
533 | endtag: ']',
|
534 | transform: function (filepath, file, i, length) {
|
535 | return ' "' + filepath + '"' + (i + 1 < length ? ',' : '');
|
536 | }
|
537 | }))
|
538 | .pipe(gulp.dest('./'));
|
539 | ```
|
540 |
|
541 | ### Injecting all javascript files into a karma config file
|
542 |
|
543 | **Code:**
|
544 |
|
545 | ```javascript
|
546 | gulp.src('./karma.conf.js')
|
547 | .pipe(inject(gulp.src(['./src/**/*.js'], {read: false}), {
|
548 | starttag: 'files: [',
|
549 | endtag: ']',
|
550 | transform: function (filepath, file, i, length) {
|
551 | return ' "' + filepath + '"' + (i + 1 < length ? ',' : '');
|
552 | }
|
553 | }))
|
554 | .pipe(gulp.dest('./'));
|
555 | ```
|
556 |
|
557 | ### Injecting files contents
|
558 |
|
559 | In order to inject files contents you have to provide custom `transform` function, that will return file contents as string. You also have to omit `{read: false}` option of `gulp.src` in this case. Example below shows how to inject contents of html partials into head of `index.html`:
|
560 |
|
561 | ***Code:***
|
562 |
|
563 | ```javascript
|
564 | gulp.src('./src/index.html')
|
565 | .pipe(inject(gulp.src(['./src/partials/head/*.html']), {
|
566 | starttag: '<!-- inject:head:{{ext}} -->',
|
567 | transform: function (filePath, file) {
|
568 | // return file contents as string
|
569 | return file.contents.toString('utf8')
|
570 | }
|
571 | }))
|
572 | .pipe(gulp.dest('./dest'));
|
573 | ```
|
574 |
|
575 | And in your `./src/index.html`:
|
576 |
|
577 | ```html
|
578 | <!DOCTYPE html>
|
579 | <html>
|
580 | <head>
|
581 | <title>My index</title>
|
582 | <!-- inject:head:html -->
|
583 | <!-- contents of html partials will be injected here -->
|
584 | <!-- endinject -->
|
585 | </head>
|
586 | <body>
|
587 | </body>
|
588 | </html>
|
589 | ```
|
590 |
|
591 | ### Injecting files contents based on file path
|
592 |
|
593 | In order to inject files based on file path you have to provide custom `starttag` which includes `{{path}}`. Additionally, in order to inject file contents include `transform` function, that will return file contents as string. You also have to omit `{read: false}` option of `gulp.src` in this case. Path can be either absolute, or relative in which case you should set [`options.relative`] to true. Example below shows how to inject contents of html partials into `index.html`:
|
594 |
|
595 | ***Code:***
|
596 |
|
597 | ```javascript
|
598 | gulp.src('./src/index.html')
|
599 | .pipe(inject(gulp.src(['./src/partials/head/*.html']), {
|
600 | starttag: '<!-- inject:{{path}} -->',
|
601 | relative: true,
|
602 | transform: function (filePath, file) {
|
603 | // return file contents as string
|
604 | return file.contents.toString('utf8')
|
605 | }
|
606 | }))
|
607 | .pipe(gulp.dest('./dest'));
|
608 | ```
|
609 |
|
610 | And in your `./src/index.html`:
|
611 |
|
612 | ```html
|
613 | <!DOCTYPE html>
|
614 | <html>
|
615 | <head>
|
616 | <title>My index</title>
|
617 | <!-- inject:path/to/your/file.ext -->
|
618 | <!-- contents of html partials will be injected here -->
|
619 | <!-- endinject -->
|
620 | </head>
|
621 | <body>
|
622 | </body>
|
623 | </html>
|
624 | ```
|
625 |
|
626 | ## API
|
627 |
|
628 | ### inject(sources, options)
|
629 |
|
630 | Parameter: `sources`
|
631 | Type: `Stream`
|
632 |
|
633 | Provide a Vinyl File Stream as input to `inject`, see examples above.
|
634 |
|
635 |
|
636 | Parameter: `options`
|
637 | Type: `Object`
|
638 |
|
639 | For available options see [Options](#options)
|
640 |
|
641 | ### Options
|
642 |
|
643 | #### options.ignorePath
|
644 | Type: `String` or `Array`
|
645 |
|
646 | Default: `NULL`
|
647 |
|
648 |
|
649 | A path or paths that should be removed from each injected file path.
|
650 |
|
651 | This could also be solved by setting the `cwd` option for your `gulp.src` streams, each source file's `cwd` is automatically removed from its path before injection (if not [`options.relative`](#optionsrelative) is set to `true`, see below).
|
652 |
|
653 |
|
654 | #### options.relative
|
655 | Type: `Boolean`
|
656 |
|
657 | Default: `false`
|
658 |
|
659 |
|
660 | If set to `true` paths for the injected files will be relative to each target file, this also means that each source file's `cwd` is not necessary to remove from its path.
|
661 |
|
662 |
|
663 | #### options.addPrefix
|
664 | Type: `String`
|
665 |
|
666 | Default: `NULL`
|
667 |
|
668 |
|
669 | A path that should be prefixed to each injected file path.
|
670 |
|
671 | #### options.addSuffix
|
672 | Type: `String`
|
673 |
|
674 | Default: `NULL`
|
675 |
|
676 |
|
677 | A path that should be suffixed to each injected file path.
|
678 |
|
679 | #### options.addRootSlash
|
680 | Type: `Boolean`
|
681 |
|
682 | Default: [`!options.relative`](#optionsrelative)
|
683 |
|
684 |
|
685 | The root slash is automatically added at the beginning of the path ('/'), or removed if set to `false`.
|
686 |
|
687 | #### options.name
|
688 | Type: `String`
|
689 |
|
690 | Default: `"inject"`
|
691 |
|
692 |
|
693 | Used in the default [start](#optionsstarttag) and [end](#optionsendtag) tags below.
|
694 |
|
695 | #### options.removeTags
|
696 | Type: `Boolean`
|
697 |
|
698 | Default: `false`
|
699 |
|
700 |
|
701 | When `true` the start and end tags will be removed when injecting files.
|
702 |
|
703 | #### options.empty
|
704 | Type: `Boolean`
|
705 |
|
706 | Default: `false`
|
707 |
|
708 |
|
709 | When `true` all tags without corresponding files will be emptied.
|
710 |
|
711 | [**Warning** this has the potential issue of emptying more than expected.](https://github.com/klei/gulp-inject/issues/135)
|
712 |
|
713 |
|
714 | #### options.starttag
|
715 |
|
716 | **Type:** `String`|`Function(targetExt, sourceExt)`
|
717 |
|
718 | **Params (if function):**
|
719 | - `targetExt` - The file extension of the target file
|
720 | - `sourceExt` - The file extension of source file
|
721 |
|
722 | **Purpose:**
|
723 |
|
724 | Used to dynamically set starting placeholder tag depending on file extensions.
|
725 | In the provided string, or the string returned from the given function, the string `{{ext}}` is replaced with the source file extension name, e.g. "css", "js" or "html". `{{name}}` will be replaced by [`options.name`](#optionsname). `{{path}}` will be replaced by path to source file (when used together with [`options.relative`] it will allow relative path to source file.
|
726 |
|
727 | ##### Default:
|
728 |
|
729 | A function dependent on target file type and source file type that returns:
|
730 |
|
731 | * html as target: `<!-- {{name}}:{{ext}} -->`
|
732 | * haml as target: `-# {{name}}:{{ext}}`
|
733 | * jade as target: `//- {{name}}:{{ext}}`
|
734 | * pug as target: `//- {{name}}:{{ext}}`
|
735 | * jsx as target: `{/* {{name}}:{{ext}} */}`
|
736 | * slm as target: `/ {{name}}:{{ext}}`
|
737 | * less as target: `/* {{name}}:{{ext}} */`
|
738 | * sass, scss as target: `/* {{name}}:{{ext}} */`
|
739 |
|
740 | #### options.endtag
|
741 |
|
742 | **Type:** `String`|`Function(targetExt, sourceExt)`
|
743 |
|
744 | **Params (if function):**
|
745 | - `targetExt` - The file extension of the target file
|
746 | - `sourceExt` - The file extension of source file
|
747 |
|
748 | **Purpose:**
|
749 |
|
750 | Used to dynamically set ending placeholder tag depending on file extensions.
|
751 | In the provided string, or the string returned from the given function, the string `{{ext}}` is replaced with the source file extension name, e.g. "css", "js" or "html". `{{name}}` will be replaced by [`options.name`](#optionsname). `{{path}}` will be replaced by path to source file.
|
752 |
|
753 | ##### Default:
|
754 |
|
755 | A function dependent on target file type and source file type that returns:
|
756 |
|
757 | * html as target: `<!-- endinject -->`
|
758 | * haml as target: `-# endinject`
|
759 | * jade as target: `//- endinject`
|
760 | * pug as target: `//- endinject`
|
761 | * jsx as target: `{/* endinject */}`
|
762 | * slm as target: `/ endinject`
|
763 | * less as target: `/* endinject */`
|
764 | * sass, scss as target: `/* endinject */`
|
765 |
|
766 | #### options.transform
|
767 |
|
768 | **Type**: `Function(filepath, file, index, length, targetFile)`
|
769 |
|
770 | **Params:**
|
771 | - `filepath` - The "unixified" path to the file with any `ignorePath`'s removed, `addPrefix` and `addSuffix` added
|
772 | - `file` - The [File object](https://github.com/wearefractal/vinyl) to inject given from `gulp.src`
|
773 | - `index` - 0-based file index
|
774 | - `length` - Total number of files to inject for the current file extension
|
775 | - `targetFile` - The target [file](https://github.com/wearefractal/vinyl) to inject into
|
776 |
|
777 | **Purpose:**
|
778 |
|
779 | Used to generate the content to inject for each file.
|
780 |
|
781 | ##### Default:
|
782 |
|
783 | [A function](#injecttransform) dependent on target file type and source file type that returns:
|
784 |
|
785 | **Injecting into `html`**
|
786 |
|
787 | * css files: `<link rel="stylesheet" href="<filename>.css">`
|
788 | * js files: `<script src="<filename>.js"></script>`
|
789 | * coffee files: `<script type="text/coffeescript" src="<filename>.coffee"></script>`
|
790 | * html files: `<link rel="import" href="<filename>.html">`
|
791 | * png files: `<img src="<filename>.png">`
|
792 | * gif files: `<img src="<filename>.gif">`
|
793 | * jpg files: `<img src="<filename>.jpg">`
|
794 | * jpeg files: `<img src="<filename>.jpeg">`
|
795 |
|
796 | If `options.selfClosingTag` is `true` the default transformer above will make the `<link>` and `<img>` tags self close, i.e: `<link ... />` and `<img ... />` respectively.
|
797 |
|
798 | **Injecting into `jsx`**
|
799 |
|
800 | The same as for injecting into `html` above with [`options.selfClosingTag`](#optionsselfclosingtag) set to `true`.
|
801 |
|
802 | **Injecting into `jade`**
|
803 |
|
804 | * css files: `link(rel="stylesheet", href="<filename>.css")`
|
805 | * js files: `script(src="<filename>.js")`
|
806 | * coffee files: `script(type="text/coffeescript", src="<filename>.coffee")`
|
807 | * html files: `link(rel="import", href="<filename>.html")`
|
808 | * png files: `img(src="<filename>.png")`
|
809 | * gif files: `img(src="<filename>.gif")`
|
810 | * jpg files: `img(src="<filename>.jpg")`
|
811 | * jpeg files: `img(src="<filename>.jpeg")`
|
812 |
|
813 | **Injecting into `pug`**
|
814 |
|
815 | * css files: `link(rel="stylesheet", href="<filename>.css")`
|
816 | * js files: `script(src="<filename>.js")`
|
817 | * coffee files: `script(type="text/coffeescript", src="<filename>.coffee")`
|
818 | * html files: `link(rel="import", href="<filename>.html")`
|
819 | * png files: `img(src="<filename>.png")`
|
820 | * gif files: `img(src="<filename>.gif")`
|
821 | * jpg files: `img(src="<filename>.jpg")`
|
822 | * jpeg files: `img(src="<filename>.jpeg")`
|
823 |
|
824 | **Injecting into `slm`**
|
825 |
|
826 | * css files: `link rel="stylesheet" href="<filename>.css"`
|
827 | * js files: `script src="<filename>.js"`
|
828 | * coffee files: `script type="text/coffeescript" src="<filename>.coffee"`
|
829 | * html files: `link rel="import" href="<filename>.html"`
|
830 | * png files: `img src="<filename>.png"`
|
831 | * gif files: `img src="<filename>.gif"`
|
832 | * jpg files: `img src="<filename>.jpg"`
|
833 | * jpeg files: `img src="<filename>.jpeg"`
|
834 |
|
835 | **Injecting into `haml`**
|
836 |
|
837 | * css files: `%link{rel:"stylesheet", href:"<filename>.css"}`
|
838 | * js files: `%script{src:"<filename>.js"}`
|
839 | * coffee files: `%script{type:"text/coffeescript", src:"<filename>.coffee"}`
|
840 | * html files: `%link{rel:"import", href:"<filename>.html"}`
|
841 | * png files: `%img{src:"<filename>.png"}`
|
842 | * gif files: `%img{src:"<filename>.gif"}`
|
843 | * jpg files: `%img{src:"<filename>.jpg"}`
|
844 | * jpeg files: `%img{src:"<filename>.jpeg"}`
|
845 |
|
846 | **Injecting into `less`**
|
847 |
|
848 | * css files: `@import "<filename>.css";`
|
849 | * less files: `@import "<filename>.less";`
|
850 |
|
851 | **Injecting into `scss`**
|
852 |
|
853 | * css files: `@import "<filename>.css";`
|
854 | * scss files: `@import "<filename>.scss";`
|
855 | * sass files: `@import "<filename>.sass";`
|
856 |
|
857 | **Injecting into `sass`**
|
858 |
|
859 | * css files: `@import "<filename>.css"`
|
860 | * sass files: `@import "<filename>.sass"`
|
861 | * scss files: `@import "<filename>.scss"`
|
862 |
|
863 | #### options.selfClosingTag
|
864 | Type: `Boolean`
|
865 |
|
866 | Default: `false`
|
867 |
|
868 | Affects the default `options.transform` function, see above.
|
869 |
|
870 |
|
871 | #### options.quiet
|
872 | Type: `Boolean`
|
873 |
|
874 | Default: `false`
|
875 |
|
876 | Lower the verbosity by setting this to true, suppressing the logging of successful injections.
|
877 |
|
878 |
|
879 | #### ~~options.templateString~~
|
880 |
|
881 | ***DEPRECATED!***
|
882 |
|
883 | *Deprecated since `v.1.0`. Use [`gulp-file`](https://www.npmjs.org/package/gulp-file) instead:*
|
884 |
|
885 | ```javascript
|
886 | var gulp = require('gulp');
|
887 | var file = require('gulp-file');
|
888 | var inject = require('gulp-inject');
|
889 |
|
890 | file('index.html', '<html><head></head></html>')
|
891 | .pipe(inject(gulp.src(['./src/app/**/*.js']), {
|
892 | starttag: '<head>',
|
893 | endtag: '</head>'
|
894 | }))
|
895 | .pipe(gulp.dest('./dest'));
|
896 | ```
|
897 |
|
898 | #### ~~options.sort~~
|
899 |
|
900 | ***DEPRECATED!***
|
901 |
|
902 | *Deprecated since `v.1.0`. Use [`sort-stream`](https://www.npmjs.org/package/sort-stream) instead:*
|
903 |
|
904 | ```javascript
|
905 | var gulp = require('gulp');
|
906 | var sort = require('sort-stream');
|
907 | var inject = require('gulp-inject');
|
908 |
|
909 | gulp.src('index.html')
|
910 | .pipe(inject(
|
911 | gulp.src(['./src/app/**/*.js'])
|
912 | .pipe(sort(function (a, b) {
|
913 | // Sort condition here...
|
914 | }))
|
915 | ))
|
916 | .pipe(gulp.dest('./dest'));
|
917 | ```
|
918 |
|
919 | ### inject.transform
|
920 |
|
921 | The default transform function is exposed in the public API.
|
922 |
|
923 | For more details see [the code with tests](https://github.com/klei/gulp-inject/tree/master/src/transform).
|
924 |
|
925 | ##### inject.transform.html
|
926 |
|
927 | The default transform function for files into `html`, or other file types not `jade`, `pug`, `jsx`, `slm`, `less`, `scss`, `sass` or `haml`.
|
928 |
|
929 | ##### inject.transform.jade
|
930 |
|
931 | The default transform function for files into `jade`.
|
932 |
|
933 | ##### inject.transform.pug
|
934 |
|
935 | The default transform function for files into `pug`.
|
936 |
|
937 | ##### inject.transform.jsx
|
938 |
|
939 | The default transform function for files into `jsx`.
|
940 |
|
941 | ##### inject.transform.slm
|
942 |
|
943 | The default transform function for files into `slm`.
|
944 |
|
945 | ##### inject.transform.haml
|
946 |
|
947 | The default transform function for files into `haml`.
|
948 |
|
949 | ##### inject.transform.less
|
950 |
|
951 | The default transform function for files into `less`.
|
952 |
|
953 | ##### inject.transform.sass
|
954 |
|
955 | The default transform function for files into `sass`.
|
956 |
|
957 | ##### inject.transform.scss
|
958 |
|
959 | The default transform function for files into `scss`.
|
960 |
|
961 |
|
962 | ## License
|
963 |
|
964 | [MIT](http://en.wikipedia.org/wiki/MIT_License) © [Joakim Carlstein](http://joakim.beng.se)
|
965 |
|
966 | [npm-url]: https://npmjs.org/package/gulp-inject
|
967 | [npm-image]: https://badge.fury.io/js/gulp-inject.svg
|
968 |
|
969 | [travis-url]: http://travis-ci.org/klei/gulp-inject
|
970 | [travis-image]: https://secure.travis-ci.org/klei/gulp-inject.svg?branch=master
|
971 |
|
972 | [depstat-url]: https://david-dm.org/klei/gulp-inject
|
973 | [depstat-image]: https://david-dm.org/klei/gulp-inject.svg
|
974 |
|
975 | [codestyle-url]: https://github.com/sindresorhus/xo
|
976 | [codestyle-image]: https://img.shields.io/badge/code%20style-XO-5ed9c7.svg?style=flat
|