1.1.2 • Public • Published

Gulp tributary

npm version

Includes one file inside another by replacing placeholders with a file. Just like the #include directive of server side includes.

There are several other Gulp plugins that also do this, the differece with this one are the included files are taken from a Gulp stream rather than directly from the file system.

There are also compatible with Vinyl streams.


Given the files:

    <title>My awesome page</title>
    <script><!-- include "my.js" --></script> 
function myAwesomeFunction() {}

We can put them together to create:

    <title>My awesome page</title>
    <script>function myAwesomeFunction() {}</script> 

By using the following grunt task:

var tributary = require('gulp-tributary');
    .pipe( tributary( gulp.src('script.js') ) )
    .pipe( gulp.dest('dest') );

However, if we also wanted to minifiy the javascript we could do the following:

var jsSource = gulp.src('script.js')
    .pipe( require('gulp-uglify')() );
    .pipe( tributary( jsSource ) )
    .pipe( gulp.dest('dest') );

tributary( source, options )

  • source a stream of Vinyl files that might be included, e.g. gulp.src()
  • options.mediaType specify the media type of the files. Used to choose the placeholder tags
  • options.placeholder an Array containing the start and end parts of the placeholder
  • options.ignoreMissingFiles Boolean, default = false, if true don't error if an included file cannot be found.
  • options.delimiter the delimiter to use around the filename. Defaults to "


The default placeholders depend on the media type of the file and are determined from the extension. The html placeholder is used as the default.

They must be matched exactly. The filetype delimiter is fixed.

  • text/html - .htm - <!-- include "filename" -->
  • application/javascript - .js - /* include "filename" */
  • text/css - .js, .less, .sass, .scss - /* include "filename" */

These defaults can be overriden using the placeholder option. The media type of the file can be overriden using the mediaType option.

The default templates are set on a property of the tributary object called placeholders which can be used to modfiy them globally.


npm i gulp-tributary

DownloadsWeekly Downloads






Last publish


  • mrdaniellewis