API

The API for nunjucks covers rendering templates, adding filters and extensions, customizing template loading, and more.

User-Defined Templates Warning

nunjucks does not sandbox execution so it is not safe to run user-defined templates or inject user-defined content into template definitions. On the server, you can expose attack vectors for accessing sensitive data and remote code execution. On the client, you can expose cross-site scripting vulnerabilities even for precompiled templates (which can be mitigated with a strong CSP). See this issue for more information.

Simple API

If you don't need deep customization of the system, you can use this simple higher-level API for loading and rendering templates.

render

var res = nunjucks.render('foo.html');

var res = nunjucks.render('foo.html', { username: 'James' });

nunjucks.render('async.html', function(err, res) {
});

renderString

var res = nunjucks.renderString('Hello {{ username }}', { username: 'James' });

compile

var template = nunjucks.compile('Hello {{ username }}');
template.render({ username: 'James' });

configure

nunjucks.configure('views');

// if in the browser, you probably want to use an absolute URL
nunjucks.configure('/views');

nunjucks.configure({ autoescape: true });

nunjucks.configure('views', {
    autoescape: true,
    express: app,
    watch: true
});

var env = nunjucks.configure('views');
// do stuff with env

installJinjaCompat

That's it for the simple API! If you want total control over how templates are loaded, and more customization, you need to manually set up the system as seen below.

Environment

The Environment class is the central object which handles templates. It knows how to load your templates, and internally templates depend on it for inheritance and including templates. The simple API above dispatches everything to an Environment instance that it keeps for you.

You can manually handle it if you want, which allows you to specify custom template loaders.

constructor

// the FileSystemLoader is available if in node
var env = new nunjucks.Environment(new nunjucks.FileSystemLoader('views'));

var env = new nunjucks.Environment(new nunjucks.FileSystemLoader('views'),
                          { autoescape: false });

var env = new nunjucks.Environment([new nunjucks.FileSystemLoader('views'),
                           new MyCustomLoader()]);

// the WebLoader is available if in the browser
var env = new nunjucks.Environment(new nunjucks.WebLoader('/views'));

render

var res = nunjucks.render('foo.html');

var res = nunjucks.render('foo.html', { username: 'James' });

nunjucks.render('async.html', function(err, res) {
});

renderString

var res = nunjucks.renderString('Hello {{ username }}', { username: 'James' });

addFilter

getFilter

addExtension

removeExtension

getExtension

hasExtension

addGlobal

getGlobal

getTemplate

var tmpl = env.getTemplate('page.html');

var tmpl = env.getTemplate('page.html', true);

env.getTemplate('from-async-loader.html', function(err, tmpl) {
});

express

var app = express();
env.express(app);

app.get('/', function(req, res) {
    res.render('index.html');
});

opts.autoescape

'load' event

Template

A Template is an object that handles the compiling of template strings and rendering them. Usually the Environment handles them for you, but you can easily use it yourself. If you don't connect a template with an environment, you can't include or inherit any other templates.

constructor

var tmpl = new nunjucks.Template('Hello {{ username }}');

tmpl.render({ username: "James" }); // -> "Hello James"

render

Loader

A loader is an object that takes a template name and loads it from a source, such as the filesystem or network. The following two builtin loaders exist, each for different contexts.

FileSystemLoader

// Loads templates from the "views" folder
var env = new nunjucks.Environment(new nunjucks.FileSystemLoader('views'));

NodeResolveLoader

WebLoader

// Load templates from /views
var env = new nunjucks.Environment(new nunjucks.WebLoader('/views'))

Writing a Loader

You can write loaders for more complex loading, like from a database. If you want to do this, just create an object that has a method getSource(name), where name is the name of the template. That's it.

function MyLoader(opts) {
    // configuration
}

MyLoader.prototype.getSource = function(name) {
    // load the template
    // return an object with:
    //   - src:     String. The template source.
    //   - path:    String. Path to template.
    //   - noCache: Bool. Don't cache the template (optional).
}

It can get a little more complex. If you want to track updates to templates and bust the internal cache so that you can see updates, you need to extend the Loader class. This gives you emit method that can fire events. You need to call it

var MyLoader = nunjucks.Loader.extend({
    init: function() {
        // setup a process which watches templates here
        // and call `this.emit('update', name)` when a template
        // is changed
    },

    getSource: function(name) {
        // load the template
    }
});

Asynchronous

There's one last piece: asynchronous loaders. So far, all of the loaders have been synchronous; getSource returns the source immediately. The benefit of this is that the user isn't forced to use the asynchronous API and be aware of edge cases about async templates. You might want to load from a database, however.

Just add an async: true property to your loader and it will be used asynchronously.

var MyLoader = nunjucks.Loader.extend({
    async: true,

    getSource: function(name, callback) {
        // load the template
        // ...
        callback(err, res);
    }
});

Remember that you now have to use the asynchronous API. See asynchronous support.

Warning: if you are using an asynchronous loader, you can't load templates inside for loops. You need to explicitly use the asyncEach tag if you need to load templates, which is exactly the same as for but asynchronous. More info can be found at Be Careful!.

Browser Usage

Using nunjucks in the browser takes a little more thought because you care about load and compile time. On the server-side, templates are compiled once and cached in memory and you never have to worry about it. On the client-side however, you don't want to compile templates even once, as it would result in slow page render time.

The solution is to precompile your templates into JavaScript, and load them as a simple .js file on page load.

Maybe you do want to dynamically load templates while developing, however, so that you can see changes immediately without recompiling. Nunjucks tries to adapt to whatever workflow you want.

The only rule you must follow: always precompile your templates in production. Why? Not only is it slow to compile all your templates on page load, they are loaded synchronously over HTTP, blocking the whole page. It is slow. It does this because nunjucks isn't async by default.

Recommended Setups

These are two of the most popular ways to set up nunjucks on the client-side. Note that there are two different js files: one with the compiler, nunjucks.js, and one without the compiler, nunjucks-slim.js. Read Getting Started for a brief overview of the differences.

See Precompiling for information on precompiling templates.

Setup #1: only precompile in production

This method will give you a setup that dynamically loads templates while developing (you can see changes immediately), but uses precompiled templates in production.

1. Load nunjucks.js with either a script tag or a module loader.
2. Render templates (example)!
3. When pushing to production, precompile the templates into a js file and load it on the page

An optimization is to use nunjucks-slim.js instead of nunjucks.js in production since you are using precompiled templates there. It's 8K instead of 20K because it doesn't contain the compiler. This complicates the setup though because you are using different js files between dev and prod, so it may or may not be worth it.

Setup #2: always precompile

This method always uses precompiled templates while developing and in production, which simplifies the setup. However, you're going to want something that automatically recompiles templates while developing unless you want to manually recompile them after every change.

1. For development, use the grunt or gulp tasks to watch your template directory for changes and automatically precompile them into a js file
2. Load nunjucks-slim.js and templates.js, or whatever you named the precompiled js file, with either a script tag or a module loader.
3. Render templates (example)!

With this method, there are no differences between development and production code. Simply commit the templates.js file and deploy the same code to production.

Precompiling

To precompile your templates, use the nunjucks-precompile script that comes with nunjucks. You can pass it a directory or a file and it will generate all the JavaScript for your templates.

// Precompiling a whole directory
$ nunjucks-precompile views > templates.js

// Precompiling individual templates
$ nunjucks-precompile views/base.html >> templates.js
$ nunjucks-precompile views/index.html >> templates.js
$ nunjucks-precompile views/about.html >> templates.js

All you have to do is simply load templates.js on the page, and the system will automatically use the precompiled templates. There are zero changes necessary.

There are various options available to the script. Simply invoke nunjucks-precompile to see more info about them. Note that names of all asynchronous filters need to passed to the script since they need to be known at compile-time. You can pass a comma-delimited list of async filters with -a, like -a foo,bar,baz. If you only use normal synchronous filters, you don't need to do anything.

Extensions cannot be specified with this script. You must use the precompile API below if you use them.

API

There is also an API if you want to programmatically precompile templates. You'll want to do this if you use extensions or you use asynchronous filters, both of which need to be known at compile-time. You can pass an Environment object straight into the precompiler and it will get the extensions and filters from it. You should share the same Environment object between the client and server to keep everything in sync.

precompile

var env = new nunjucks.Environment();

// extensions must be known at compile-time
env.addExtension('MyExtension', new MyExtension());

// async filters must be known at compile-time
env.addFilter('asyncFilter', function(val, cb) {
  // do something
}, true);

nunjucks.precompile('/dir/to/views', { env: env });

precompileString

Asynchronous Support

You only need to read this section if you are interested in asynchronous rendering. There is no performance benefit to this, it is solely to allow custom filters and extensions to make async calls. If you don't care about this, you should simply use the normal API like var res = env.render('foo.html');. There's no need to force the callback on you, and it's why it's optional in all the rendering functions.

As of version 1.0, nunjucks provides a way to render templates asynchronously. This means that custom filters and extensions can do stuff like fetch things from the database, and template rendering is "paused" until the callback is called.

Template loaders can be async as well, allowing you to load templates from a database or somewhere else. See Writing a Loader. If you are using an async template loader, you must use the async API. The builtin loaders that load from the filesystem and over HTTP are synchronous, which is not a performance problem because they are cached from the filesystem and you should precompile your templates and never use HTTP in production.

If you are using anything async, you need to use the async API like this:

nunjucks.render('foo.html', function(err, res) {
   // check err and handle result
});

Read more about async filters, extensions, and loaders.

Be Careful!

Nunjucks is synchronous by default. Because of this, you need to follow a few rules when writing asynchronous templates:

• Always use the async API. render should take a function that takes a callback.
• Async filters and extensions need to be known at compile-time, so you need to specify them explicitly when precompiling (see Precompiling).
• If you are using a custom template loader that is asynchronous, you can't include templates inside a for loop. This is because for will compile to an imperative JavaScript for loop. You need to explicitly use the async asyncEach tag to iterate, which is exactly the same as for except asynchronous.

Autoescaping

By default, nunjucks will escape all output. It's recommended that you do this for security reasons. If you turn off autoescaping, nunjucks will render all output as it is by default.

To deactivate it, all you have to do is pass the autoescape option as false to the Environment object.

var env = nunjucks.configure('/path/to/templates', { autoescape: false });

Customizing Syntax

If you want different tokens than {{ and the rest for variables, blocks, and comments, you can specify different tokens as the tags option:

var env = nunjucks.configure('/path/to/templates', {
  tags: {
    blockStart: '<%',
    blockEnd: '%>',
    variableStart: '<$',
    variableEnd: '$>',
    commentStart: '<#',
    commentEnd: '#>'
  }
});

Using this environment, templates will look like this:

<ul>
<% for item in items %>
  <li><$ item $></li>
<% endfor %>
</ul>

Custom Filters

To install a custom filter, use the Environment method addFilter. A filter is simply a function that takes the target object as the first argument and any arguments passed to the filter as the other arguments, in order.

var nunjucks = require('nunjucks');
var env = new nunjucks.Environment();

env.addFilter('shorten', function(str, count) {
    return str.slice(0, count || 5);
});

This adds a filter shorten which returns the first count characters in a string, with count defaulting to 5. Here is how it is used:

{# Show the first 5 characters #}
A message for you: {{ message|shorten }}

{# Show the first 20 characters #}
A message for you: {{ message|shorten(20) }}

Keyword/Default Arguments

As described in the templating section, nunjucks supports keyword/default arguments. You can write a normal javascript filter that leverages them.

All keyword arguments are passed in as a hash as the last argument. This is a filter foo that uses keyword arguments:

env.addFilter('foo', function(num, x, y, kwargs) {
   return num + (kwargs.bar || 10);
})

The template can use it like this:

{{ 5 | foo(1, 2) }}          -> 15
{{ 5 | foo(1, 2, bar=3) }}   -> 8

You must pass all of the positional arguments before keyword arguments (foo(1) is valid but foo(1, bar=10) is not). Also, you cannot set a positional argument with a keyword argument like you can in Python (such as foo(1, y=1))

Asynchronous

Asynchronous filters receive a callback to resume rendering, and are created by passing true as the third argument to addFilter.

var env = nunjucks.configure('views');

env.addFilter('lookup', function(name, callback) {
    db.getItem(name, callback);
}, true);

env.renderString('{{ item|lookup }}', function(err, res) {
    // do something with res
});

Make sure to call the callback with two arguments: callback(err, res). err can be null, of course.

Note: When precompiling, you must tell the precompiler the names of all asynchronous filters. See Precompiling.

Custom Tags

You can create more complicated extensions by creating custom tags. This exposes the parser API and allows you to do anything you want with the template.

Note: When precompiling, you must install the extensions at compile-time. You have to use the precompiling API (or the grunt or gulp tasks) instead of the script. You'll want to create an Environment object, install your extensions, and pass it to the precompiler.

An extension is a javascript object with at least two fields: tags and parse. Extensions basically register new tag names and take control of the parser when they are hit.

tags is an array of tag names that the extension should handle. parse is the method that actually parses them when the template is compiled. Additionally, there is a special node type CallExtension that you can use to call any method on your extension at runtime. This is explained more below.

Because you have to interact directly with the parse API and construct ASTs manually, this is a bit cumbersome. It's necessary if you want to do really complex stuff, however. Here are a few key parser methods you'll want to use:

• parseSignature([throwErrors], [noParens]) - Parse a list of arguments. By default it requires the parser to be pointing at the left opening parenthesis, and parses up the right one. However, for custom tags you shouldn't use parentheses, so passing true to the second argument tells it to parse a list of arguments up until the block end tag. A comma is required between arguments. Example: {% mytag foo, bar, baz=10 %}

• parseUntilBlocks(names) - Parse content up until it hits a block with a name in the names array. This is useful for parsing content between tags.

The parser API needs to be more documented, but for now read the above and check out the example below. You can also look at the source.

The most common usage is to process the content within some tags at runtime. It's like filters, but on steroids because you aren't confined to a single expression. You basically want to lightly parse the template and then get a callback into your extension with the content. This is done with the CallExtension node, which takes an extension instance, the method to call, list of arguments parsed from the tag, and a list of content blocks (parsed with parseUntilBlocks).

For example, here's how you would implement an extension that fetches content from a URL and injects it into the page:

function RemoteExtension() {
    this.tags = ['remote'];

    this.parse = function(parser, nodes, lexer) {
        // get the tag token
        var tok = parser.nextToken();

        // parse the args and move after the block end. passing true
        // as the second arg is required if there are no parentheses
        var args = parser.parseSignature(null, true);
        parser.advanceAfterBlockEnd(tok.value);

        // parse the body and possibly the error block, which is optional
        var body = parser.parseUntilBlocks('error', 'endremote');
        var errorBody = null;

        if(parser.skipSymbol('error')) {
            parser.skip(lexer.TOKEN_BLOCK_END);
            errorBody = parser.parseUntilBlocks('endremote');
        }

        parser.advanceAfterBlockEnd();

        // See above for notes about CallExtension
        return new nodes.CallExtension(this, 'run', args, [body, errorBody]);
    };

    this.run = function(context, url, body, errorBody) {
        var id = 'el' + Math.floor(Math.random() * 10000);
        var ret = new nunjucks.runtime.SafeString('<div id="' + id + '">' + body() + '</div>');
        var ajax = new XMLHttpRequest();

        ajax.onreadystatechange = function() {
            if(ajax.readyState == 4) {
                if(ajax.status == 200) {
                    document.getElementById(id).innerHTML = ajax.responseText;
                }
                else {
                    document.getElementById(id).innerHTML = errorBody();
                }
            }
        };

        ajax.open('GET', url, true);
        ajax.send();

        return ret;
    };
}

env.addExtension('RemoteExtension', new RemoteExtension());

Use it like this:

{% remote "/stuff" %}
  This content will be replaced with the content from /stuff
{% error %}
  There was an error fetching /stuff
{% endremote %}

Asynchronous

Another available node is CallExtensionAsync which is an asynchronous version of CallExtension. It calls back into your extension at runtime, with an additional parameter: a callback. Template rendering is paused until you call the callback to resume.

The run function from the above example would now look like:

this.run = function(context, url, body, errorBody, callback) {
   // do async stuff and then call callback(err, res)
};

If you create anything interesting, make sure to add it to the wiki!