Compile Twig templates with gulp. Build upon Twing.

Requires Node.js ≥ 6.0.0

npm install twing gulp-twing --save

gulp-twing declares Twing as a peer dependency. It permits using any version of Twing (starting with version 0.4.0) with gulp-twing and profits from the latest features without having to wait for gulp-twing to catch up.

var twing = require('gulp-twing');

Return an object transform stream that expects entry filenames.

• env

  A Twing environment. See Twing documentation for details.

• data

  A hash of data passed to the render function of the template. See Twing documentation for details.

• options

  An optional hash of options. The following options are supported:

  • outputExt

    The output file extension including the .. Defaults to .html.

The following examples all require importing gulp, gulp-twing, and Twing, and setting the Twing loader and env:

// top of gulpfile.js
var gulp = require('gulp');
var twing = require('gulp-twing');

var Twing = require('twing');
var loader = new Twing.TwingLoaderFilesystem('.');
var env = new Twing.TwingEnvironment(loader);

To compile all .twig files in the source directory src/ saving the output as .html in the destination directory dest/, use

// in gulpfile.js
function twig() {
    return gulp.src('src/**/*.twig')
        .pipe(twing(env))
        .pipe(gulp.dest('dest'))
}

To expose the above function to the command line in gulp 3 or gulp 4, use gulp.task:

// in twig()
gulp.task('twig', twig);

Call the function with the command gulp twing.

If you don't need to support gulp 3, you can use the more terse gulp 4 syntax

// in twig()
gulp.task(twig);

It may be convenient to use the classic syntax, for example when migrating an older gulp project's Twig compilation to Twing. This is not recommended for new projects as it is not supported by gulp 4.

// in gulpfile.js
gulp.task('twig', function() {
    return gulp.src('src/**/*.twig')
        .pipe(twing(env))
        .pipe(gulp.dest('dest'))
});

You can pass data to Twig templates during compilation with the gulp-twing's data hash.

For example, to compile the template

{# src/example.twig #}
{{ foo }}

to

<!-- dest/example.twig -->
bar

use

// in gulpfile.js
function twig() {
    return gulp.src('src/**/*.twig')
        .pipe(twing(env, {foo: 'bar'}))
        .pipe(gulp.dest('dest'))
}

By default, gulp-twing appends .html to compiled files. Changing this behavior is easy.

Use gulp-twing's outputExt option when applying the same file extension change to all source files. For example, use outputExt: '.ext' to compile example.twig as example.ext. Or use outputExt: '' to compile example.ext.twig as example.ext.

// in gulpfile.js

// src contains only *.css.twig and *.html.twig templates

function twig() {
    return gulp.src('src/**/*.twig')
        .pipe(twing(env, {}, {outputExt: ''}))
        .pipe(gulp.dest('dest'))
}

// dest will contain *.css and *.html files

If you need more control on the name of the ouput, use gulp-rename.

To compile index.css.twig, index.html.twig, and foo.twig saving the output to index.css, index.html, and foo.html, use

// in gulpfile.js
var rename = require('gulp-rename');

// src contains foo.twig, index.css.twig and index.html.twig

function twig() {
    gulp.src('src/**/*.twig')
        .pipe(twing(env))
        .pipe(rename(function(path) {
            if (path.basename.indexOf('.') > -1) {
                path.extname = '';
            }
        }))
        .pipe(gulp.dest('dest'))
}

// dest will contain foo.html, index.css and index.html

By combining gulp-rename and outputExt, you can compile index.css.twig, index.html.twig, foo.twig saving the output to index.css, index.html, and foo.ext:

// in gulpfile.js
var rename = require('gulp-rename');

// src contains foo.twig, index.css.twig and index.html.twig

function twig() {
    gulp.src('src/**/*.twig')
        .pipe(twing(env, {}, {outputExt: '.ext'}))
        .pipe(rename(function(path) {
            if (path.basename.indexOf('.') > -1) {
                path.extname = '';
            }
        }))
        .pipe(gulp.dest('dest'))
}

// dest will contain foo.ext, index.css and index.html

• Fork the main repository
• Code
• Implement tests using node-tap
• Issue a pull request keeping in mind that all pull requests must reference an issue in the issue queue

Apache-2.0 © Eric MORAND