# gulp-inject
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![XO code style][codestyle-image]][codestyle-url] [![Dependency Status][depstat-image]][depstat-url]
> A stylesheet, javascript and webcomponent reference injection plugin for [gulp](https://github.com/wearefractal/gulp). No more manual editing of your index.html!
# Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [More examples](#more-examples)
- [Injecting files relative to target files](#injecting-files-relative-to-target-files)
- [Injecting files from multiple source streams](#injecting-files-from-multiple-source-streams)
- [Injecting some files into `` and some into ``](#injecting-some-files-into-head-and-some-into-body)
- [Injecting all files for development](#injecting-all-files-for-development)
- [Injecting AngularJS scripts for development](#injecting-angularjs-scripts-for-development)
- [Injecting into a json-file](#injecting-into-a-json-file)
- [Injecting with custom `transform` function with default fallback](#injecting-with-custom-transform-function-with-default-fallback)
- [Injecting dist files into bower.json's main section](#injecting-dist-files-into-bowerjsons-main-section)
- [Injecting all javascript files into a karma config file](#injecting-all-javascript-files-into-a-karma-config-file)
- [Injecting files contents](#injecting-files-contents)
- [Injecting files contents based on file path](#injecting-files-contents-based-on-file-path)
- [API](#api)
- [inject(sources, options)](#injectsources-options)
- [inject.transform](#injecttransform)
- [License](#license)
## Introduction
`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.
Default [transforms](#optionstransform) and [placeholders](#optionsstarttag) exists for injecting files into `html`, `jade`, `pug`, `jsx` , `less`, `slm`, `haml` and `sass` / `scss` files.
## Installation
Install `gulp-inject` as a development dependency:
```shell
npm install --save-dev gulp-inject
```
## Basic usage
**The target file `src/index.html`:**
Each pair of comments are the injection placeholders (aka. tags, see [`options.starttag`](#optionsstarttag) and [`options.endtag`](#optionsendtag)).
```html
My index
```
**The `gulpfile.js`:**
```javascript
var gulp = require('gulp');
var inject = require('gulp-inject');
gulp.task('index', function () {
var target = gulp.src('./src/index.html');
// It's not necessary to read the files (will speed up things), we're only after their paths:
var sources = gulp.src(['./src/**/*.js', './src/**/*.css'], {read: false});
return target.pipe(inject(sources))
.pipe(gulp.dest('./src'));
});
```
**`src/index.html` after running `gulp index`:**
```html
My index
```
## More examples
### Injecting files relative to target files
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.
**Project structure:**
```
└── src
├── module
│ ├── module.js
│ └── module.html
└── app
├── main.js
└── index.html
```
**`src/app/index.html`:**
```html
My Index
Home
```
**`src/module/module.html`:**
```html
Module
Module
```
**`gulpfile.js`:**
```javascript
var inject = require('gulp-inject');
gulp.src('./src/**/*.html')
.pipe(inject(gulp.src('./src/**/*.js', {read: false}), {relative: true}))
.pipe(gulp.dest('./src'));
```
**Resulting `src/app/index.html`:**
```html
My Index
```
### Injecting files from multiple source streams
This example demonstrates how to inject files from multiple different streams into the same injection placeholder.
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.
**Code:**
```javascript
var es = require('event-stream'),
inject = require('gulp-inject'),
concat = require('gulp-concat'),
uglify = require('gulp-uglify');
// Concatenate vendor scripts
var vendorStream = gulp.src(['./src/vendors/*.js'])
.pipe(concat('vendors.js'))
.pipe(gulp.dest('./dist'));
// Concatenate AND minify app sources
var appStream = gulp.src(['./src/app/*.js'])
.pipe(concat('app.js'))
.pipe(uglify())
.pipe(gulp.dest('./dist'));
gulp.src('./src/index.html')
.pipe(inject(es.merge(vendorStream, appStream)))
.pipe(gulp.dest('./dist'));
```
#### Multiple sources when order is important
Use [`stream-series`](https://github.com/rschmukler/stream-series).
**Code:**
```javascript
var series = require('stream-series'),
inject = require('gulp-inject');
var vendorStream = gulp.src(['./src/vendors/*.js'], {read: false});
var appStream = gulp.src(['./src/app/*.js'], {read: false});
gulp.src('./src/index.html')
.pipe(inject(series(vendorStream, appStream))) // This will always inject vendor files before app files
.pipe(gulp.dest('./dist'));
```
### Injecting some files into `` and some into ``
#### Method 1: Use `gulp-inject`'s `starttag` option.
**`gulpfile.js`:**
```javascript
var inject = require('gulp-inject');
gulp.src('./src/index.html')
.pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {starttag: ''}))
.pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
.pipe(gulp.dest('./dist'));
```
**And in your `./src/index.html`:**
```html
My index
```
#### Method 2: Use `gulp-inject`'s `name` option.
**`gulpfile.js`:**
```javascript
var inject = require('gulp-inject');
gulp.src('./src/index.html')
.pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {name: 'head'}))
.pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
.pipe(gulp.dest('./dist'));
```
**And in your `./src/index.html`:**
```html
My index
```
### Injecting all files for development
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.
**`gulpfile.js`:**
```javascript
var bowerFiles = require('main-bower-files'),
inject = require('gulp-inject'),
stylus = require('gulp-stylus'),
es = require('event-stream');
var cssFiles = gulp.src('./src/**/*.styl')
.pipe(stylus())
.pipe(gulp.dest('./build'));
gulp.src('./src/index.html')
.pipe(inject(gulp.src(bowerFiles(), {read: false}), {name: 'bower'}))
.pipe(inject(es.merge(
cssFiles,
gulp.src('./src/app/**/*.js', {read: false})
)))
.pipe(gulp.dest('./build'));
```
**`src/index.html`:**
```html
My index
```
**Note** remember to mount `./bower_components`, `./build` and `./src/app` as static resources in your server to make this work.
### Injecting AngularJS scripts for development
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]`.
To do this you can use [`gulp-angular-filesort`](https://www.npmjs.org/package/gulp-angular-filesort) together with `gulp-inject` like so:
```javascript
var angularFilesort = require('gulp-angular-filesort'),
inject = require('gulp-inject');
gulp.src('./src/index.html')
.pipe(inject(
gulp.src('./src/app/**/*.js') // gulp-angular-filesort depends on file contents, so don't use {read: false} here
.pipe(angularFilesort())
))
.pipe(gulp.dest('./build'));
```
### Injecting into a json-file
You can customize `gulp-inject` further by using the `transform` function option, e.g. by injecting files into a json-file.
**Code:**
```javascript
gulp.src('./files.json')
.pipe(inject(gulp.src(['./src/*.js', './src/*.css', './src/*.html'], {read: false}), {
starttag: '"{{ext}}": [',
endtag: ']',
transform: function (filepath, file, i, length) {
return ' "' + filepath + '"' + (i + 1 < length ? ',' : '');
}
}))
.pipe(gulp.dest('./'));
```
Initial contents of `files.json`:
```json
{
"js": [
],
"css": [
],
"html": [
]
}
```
### Injecting with custom `transform` function with default fallback
The [default `transform`](#injecttransform) function is available to use e.g. as a default fallback.
Used here to inject Word documents as `` tags below:
**`index.html`:**
```html
My documents
`
* gif files: `
`
* jpg files: `
`
* jpeg files: `
`
If `options.selfClosingTag` is `true` the default transformer above will make the `` and `