Check out our latest tech talk, "JavaScript Supply Chain Security" presented by VP of Security, Adam Baldwin.Watch it here »


0.8.0 • Public • Published


Render Nunjucks templates with data, custom filters, custom context functions and options for other Nunjucks API features.


Install with npm

npm install --save-dev gulp-nunjucks-api


var gulp = require('gulp');
var nunjucksRender = require('gulp-nunjucks-api');
gulp.task('default', function () {
  return gulp.src('src/templates/*.html')
          src: 'src/templates',
      data: require('./global-data.json'),
      filters: require('./global-filters.js'),
      functions: require('./global-functions.js')

Example with gulp data

var gulp = require('gulp');
var nunjucksRender = require('gulp-nunjucks-api');
var data = require('gulp-data');
function getDataForFile(file){
  return {
    example: 'data loaded for ' + file.relative
gulp.task('default', function () {
    return gulp.src('src/templates/*.html')
      src: 'src/templates/'



Renders source templates using the given options to configure the Nunjucks API with custom data, extensions, filters and contextual functions.

Same options as nunjucks.configure():

  • watch (default: false) reload templates when they are changed.
  • express an express app that nunjucks should install to.
  • autoescape (default: false) controls if output with dangerous characters are escaped automatically. See Autoescaping.
  • tags (default: see nunjucks syntax) defines the syntax for nunjucks tags. See Customizing Syntax.

With the following additional options:

  • extension (default: ".html") String. File extension to output. Pass 'inherit' to use the extension of the input file.
  • src (default: undefined) String or Array. Search path(s) for nunjucks.configure().
  • data (default: {}) Ojbect. Global data merged into the Nunjucks render context.
  • errors (default: true) Boolean. Whether to emit errors to gulp or not. Set to false to let the gulp task continue on errors. See also: the verbose option.
  • extensions (default: {}) Object. Global extensions added to the Nunjucks environment. See Custom Tags.
  • filters (default: {}) Object. Global filter functions added to the Nunjucks environment. See Custom Filters.
  • functions (default: {}) Object. Global functions merged into the Nunjucks render context.
  • globals (default: undefined) Object. A single object which provides data, extensions, filters and functions objects instead of setting each of these options separately. The separate global options are merged into this base object.
  • locals (default: undefined) Boolean or String. When true, enables loading of local template context data and functions from files that match the following default pattern: "<filename>.+(js|json)". When a glob pattern string is given, the directory containing a given template will be searched using the pattern. Data and functions from all matched files are merged into the render context. Note that the token <filename> will be replaced with a given template's file name including extension. Use the <filename_noext> token instead in a custom pattern to target the file name without extension.
  • verbose (default: false) Boolean. When true, detailed operational data is logged to the console.

Render with data example

  data: {css_path: ''}

For the following template

<link rel="stylesheet" href="{{ css_path }}test.css" />

Would render

<link rel="stylesheet" href="" />

Watch mode

Nunjucks' watch feature, which is normally enabled by default, is disabled by
default for gulp. Pass watch: true to enable it:

  src: './source',
  watch: true


MIT © Devoptix LLC


Carlos G. Limardo who wrote gulp-nunjucks-render which I am forking in order to update Nunjucks and do other stuff.

Sindre Sorhus who wrote the original gulp-nunjucks for precompiling Nunjucks templates.


npm i gulp-nunjucks-api

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability