@absolunet/gulp-include

Makes inclusion of files a breeze. Enables functionality similar to that of snockets / sprockets or other file insertion compilation tools. (Extends gulp-include with custom rendering of inclusion)

Made for gulp 3

Usage

First, install gulp-include as a dev dependency: npm install --save-dev @absolunet/gulp-include

Then, add your include-comments to your file. People who have experience with sprockets or snockets will feel at home.

An include-comment looks like this:

//= include relative/path/to/file.js

or if you want to get crazy, a glob pattern like so:

//= include relative/path/to/directory/*.js

or to get even crazier, an array glob similar to commonly used in GruntJS:

//= include ['app/someFramework.js', 'app/**/*.js', '!app/vendor/**/*', 'app/someLibrary.js']

(Note: for those of you unfamiliar with the above syntax, check out https://github.com/isaacs/node-glob or http://gruntjs.com/configuring-tasks#globbing-patterns)

You can do all of this in any language, the only requirement is that the first character on the line after any #, /, or white space characters is an equal sign.

#= require_tree relative/path/to/directory

gulp-include disregards whitespace, as long as the comment-line starts with a newline followed = and contains include, require or include_tree, require_tree.

This plugin recursively expand files it includes, so you can nest includes inside of files that were themselves included. IE:

main.js:

//= include included_file.js

included_file.js:

//= include recursive_include.js

And so on recursively to an arbitrary depth.

The example below compiles a several coffee-files and js-files into a single js-file:

app.coffee:

`
//= require vendor/jquery.js
//= require vendor/modernizr.js
`

#= require controllers/AppController.coffee
#= require_tree views

class Main extends AppController
    constructor: ->
        console.log "This is main!"

window.main = new Main()

Note: The example above uses backticks (`) to allow gulp-coffee to compile inline javascript

gulpfile.js:

var gulp		= require('gulp'),
    include		= require('@absolunet/gulp-include'),
    coffee		= require('gulp-coffee');

gulp.task("scripts", function() {
    gulp.src('src/js/app.coffee')
        .pipe( include() )
        .pipe( coffee() )
        .pipe( gulp.dest("dist/js") )
});

gulp.task("default", "scripts");

jshtml

//= jshtml relative/path/to/file

or if you want to get a directory

//= jshtml_directory relative/path/to/directory

Example

The example below compiles several jsrender files into a single js-file:

app.js:

//= jshtml common/templates/item
//= jshtml_directory cart/templates

app.tmpl.common_item.render();
app.tmpl.cart_list1.render();

Options

• extensions (optional)
  • Takes a String or an Array of extensions, eg: "js" or ["js", "coffee"]
  • If set, all inclusions that does not match the extension(s) will be ignored
• basePath (optional)
  • Takes a String path
  • If set, all inclusions will be based from the basePath instead of being relative to the file
• autoExtension (optional)
  • Takes a Boolean
  • If set, all inclusions will automatically have the current file extension added to them
• partialPrefix (optional)
  • Takes a Boolean
  • If set, all inclusions will be tried with an underscore-prefixed filename (SASS style)
• fileProcess (optional)
  • Takes a Function
  • If set, will be called back with the file content to be processed an returned

Documentation

Visit the http://absolunet.github.io/nwayo website for all the things.

Release history

Forked from gulp-include v1.1.0

License

See the license.