gulp-asset-transform

A fully async Usemin-like Gulp library

Inspired by gulp-usemin

Status

Installation

Using npm:

npm install gulp-asset-transform

Documentation

• comment directive explanation
• html
• gulpfile
• tasks array
• reusing pipelines
• stream function
• remove
• implicit tag template references
• tag templates
• explicit tags
• concat
• legacy directives

Examples

var at = require('gulp-asset-transform');

### comment directive explanation Processing is defined with comments that enclose asset tags ```html ```

Each start directive is composed of a few parts, some of which are optional. The required portion

<!-- at:some_pipeline_id -->

Additionally you can include a desired filename and a tag template to use in case you don't want to match on the extension of the desired filename.

<!-- at:some_pipeline_id >> tag_template_name:sub/path/and/filename.ext -->

### html ```html

<!-- at:id1 >> assets/site.css -->
<link rel="stylesheet/less" type="text/css" href="less/less1.less">
<link rel="stylesheet/less" type="text/css" href="less/less2.less">
<!-- at:end -->

<!-- at:id2 >> assets/site.js -->
<script src="js/js1.js"></script>
<script src="js/js2.js"></script>
<!-- at:end -->

<!-- at:remove -->
<script src="js/less.js"></script>
<!-- at:end -->

``` ### gulpfile ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tasks:[less(), minifyCss(), 'concat'] }, id2: { stream:function(filestream, outputFilename){ return filestream .pipe(uglify()) .pipe(concat(outputFilename)); //concat is gulp-concat } } })) .pipe(gulp.dest('build/client')); }); ``` ### tasks array You can set the tasks key on the configuration object to an array of gulp tasks. ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tasks:[less(), minifyCss(), 'concat'] } })) .pipe(gulp.dest('build/client')); }); ```

If you use the tasks array configuration, gulp-concat is provided for you via 'concat', and the filename is parsed from the tag field.

### reusing pipelines If you need to call the same pipeline twice, you need to define each task as a function that returns the stream object that should be used. This function also receives the filename as the only parameter.

gulp.task('build', function () {
  gulp.src('./src/client/index.html')
    .pipe(at({
      less: {
        tasks: [
          less,
          minifyCss,
          function (filename) { return concat(filename); }
        ]
      }
    }))
    .pipe(gulp.dest('build/client'));
});

### stream function Alternatively, you can set the stream key on the configuration object to a function that returns a gulp stream. The function receives two arguments, the glob stream and the output filename (for concat). While more verbose than the tasks array, it has the advantage of supporting logic.

gulp.task('build', function() {
    gulp.src('./src/client/index.html')
        .pipe(at({
            id2: {
                stream:function(filestream, outputFilename){
                    return filestream
                        .pipe(uglify())
                        .pipe(concat(outputFilename)); //concat is gulp-concat
                }
            }
        }))
        .pipe(gulp.dest('build/client'));
});

### remove A special 'remove' directive is provided to remove any tags that should not survive the build process. ### implicit tag template references A js and css template have been provided. The template to be used is inferred from the extension of the desired filename.

<!-- at:id >> assets/site.css -->
<link rel="stylesheet/less" type="text/css" href="less/less1.less">
<link rel="stylesheet/less" type="text/css" href="less/less2.less">
<!-- at:end -->

This will use the tag template assigned to 'css'.

These can be overridden by explicitly specifying a template reference before the desired filename.

<!-- at:id >> css1:assets/site.css -->
<link rel="stylesheet/less" type="text/css" href="less/less1.less">
<link rel="stylesheet/less" type="text/css" href="less/less2.less">
<!-- at:end -->

In this case, we expect to use a tag template called 'css1'. If you specify something other than css or js, you will need to provide the tag template.

### tag templates Tag templates can be overridden at both the global and task level ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tasks:[less(), minifyCss(), 'concat'], tagTemplate:function(filename){ return ''} }, id2: { tasks:[uglify(), 'concat'], } },{ tagTemplates:{ js:function(filename){ return ''} } })) .pipe(gulp.dest('build/client')); }); ``` All asset transform blocks with a desired filename with a '.js' extension and all blocks using ' >> js: ... ' will return '``````'. All asset transform blocks using the pipelineId 'id1' will return '``````'. ### explicit tags An explicit tag can be provided for a block. ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tag:'', tasks:[less(), minifyCss(), 'concat'] }, id2: { tasks:[uglify(), 'concat'], } })) .pipe(gulp.dest('build/client')); }); ``` ### concat The concat task can be invoked in basically two ways, by using literal string `'concat:'` and Asset Transform's helper function `.concat([[, separator]])`. The **filename** argument is optional and if set it will be used to define the output file name. The default value is the name defined in the **at** block. The **separator** argument is also optional and is used to define the separator that will join all files contents. For instance, in case there are two files named **file_1** and **file_2** and the separator is '`,`' (comma) the output would be `,`. Example: ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tasks:[uglify(), 'concat:;\n'] }, id2: { tasks:[uglify(), at.concat('id2.js', ';\n'] } })) .pipe(gulp.dest('build/client')); }); ``` ### legacy directives In effort to conform to the more popular ```build/endbuild``` directives, you can override any of the regular expressions by supplying a regExps object. The alternate path in the comment directive will be ignored. ```javascript gulp.task('build', function() { gulp.src('./src/client/index.html') .pipe(at({ id1: { tasks:[less(), minifyCss(), 'concat'] }, id2: { tasks:[uglify(), 'concat'] } },{ regExps:{ start: //gim, end: //gim //script: regexp for script tags //link: regexp for link tags } })) .pipe(gulp.dest('build/client')); }); ```