Nunjucks is a powerful templating engine for JavaScript, inspired by Jinja2. It is designed to be fast, extendable, and easy to use, making it suitable for both server-side and client-side applications.
Template Rendering
Nunjucks allows you to render templates with dynamic data. In this example, the template 'Hello {{ name }}!' is rendered with the context { name: 'World' }, resulting in 'Hello World!'.
const nunjucks = require('nunjucks');
nunjucks.configure({ autoescape: true });
const renderedString = nunjucks.renderString('Hello {{ name }}!', { name: 'World' });
console.log(renderedString);Template Inheritance
Nunjucks supports template inheritance, allowing you to create a base template and extend it in other templates. This example shows a base template 'base.html' and an extending template 'index.html'. The rendered output will have the title 'Home' and the content 'Welcome to the homepage!'.
const nunjucks = require('nunjucks');
nunjucks.configure('views');
// base.html
// <html>
// <head><title>{% block title %}Default Title{% endblock %}</title></head>
// <body>{% block content %}{% endblock %}</body>
// </html>
// index.html
// {% extends 'base.html' %}
// {% block title %}Home{% endblock %}
// {% block content %}Welcome to the homepage!{% endblock %}
const renderedString = nunjucks.render('index.html');
console.log(renderedString);Custom Filters
Nunjucks allows you to create custom filters to manipulate data within templates. In this example, a custom filter 'shorten' is created to truncate a string to a specified length. The template 'Result: {{ message | shorten(7) }}' will render as 'Result: Hello, ' when provided with the context { message: 'Hello, World!' }.
const nunjucks = require('nunjucks');
nunjucks.configure();
nunjucks.addFilter('shorten', function(str, count) {
return str.slice(0, count || 5);
});
const renderedString = nunjucks.renderString('Result: {{ message | shorten(7) }}', { message: 'Hello, World!' });
console.log(renderedString);Handlebars is another popular templating engine for JavaScript. It uses a similar syntax to Nunjucks but is more focused on simplicity and logic-less templates. Handlebars is known for its ease of use and integration with various frameworks.
EJS (Embedded JavaScript) is a templating engine that allows you to generate HTML with plain JavaScript. It is less feature-rich compared to Nunjucks but is very straightforward and easy to use, making it a good choice for simple templating needs.
Pug, formerly known as Jade, is a high-performance template engine heavily influenced by Haml. It uses indentation-based syntax, which can be more concise but also has a steeper learning curve compared to Nunjucks. Pug is known for its clean and readable templates.
Nunjucks is a full featured templating engine for javascript. It is a direct port of the Python-powered jinja2 templating engine and aims to be feature-complete with jinja2.
It was born out of frustration with other javascript templating engines. The most popular ones either are ugly and don't abstract enough (EJS) or have too different of a syntax (Jade).
The only other project like this is jinjs, which seems to have been abandoned. The code is also not Javascript, but Coco, is difficult to work on, has bugs, and is missing features. Nunjucks hopes to be a robust, pure javascript, and easily extended port of jinja2.
npm install nunjucks
{{ foo('bar', 1) }}+ - * / < > == and moreincluderaw tagView jinja2's homepage for a full list of features. Like that page says, "Jinja is beautiful":
{% extends "layout.html" %}
{% block body %}
<ul>
{% for user in users %}
<li><a href="{{ user.url }}">{{ user.username }}</a></li>
{% endfor %}
</ul>
{% endblock %}
You can use filters to add a little bit of logic to your templates:
{% for category, members in items | groupby('category') %}
<h1>{{ name }}</h1>
<ul>
{% for item in members %}
<li>{{ item.description }}</li>
{% endfor %}
</ul>
{% endfor %}
This groups a list of objects by the "category" attribute so that you can list them by category. Nunjucks comes with several builtin filters (needs documentation) and the ability to add your own.
First, require nunjucks:
var nunjucks = require('nunjucks');
You can create a template from a string and render it:
var tmpl = new nunjucks.Template('Hello {{ username }}');
console.log(tmpl.render({ username: "james" }));
You can use an environment which allows you to fetch files from the
file system. See the Environment class for more details.
var env = new nunjucks.Environment();
var tmpl = env.getTemplate('test.html');
console.log(tmpl.render({ username: "james" }));
You can also tell nunjucks to install itself in your express app.
Assuming your templates are in the templates folder:
var nunjucks = require('nunjucks');
var loaders = nunjucks.loaders;
var express = require('express');
var env = new nunjucks.Environment(new loaders.FileSystemLoader('templates'));
env.express(app);
The FileSystemLoader takes a path, so change it to wherever your
templates live.
There are a few differences due to different semantics between javascript and Python or missing features. Items marked "todo" are ones I intend to implement soon. Other ones may be implemented at some point but are more obscure and not as important.
Missing features and differences:
{%- and -%} (todo)self variable (todo)for if bar else baz (todo)for loop needs special variables like loop.first (todo)set tag (todo)with context does not existif i is divisibleby(3){% endblock content %}# for item in seqblock inside of for loops does not workAPI.I've been unhappy with any of the existing ones for javascript. Mustache is great, but it's not really built to be the main templating system of a large app. It lacks sophisticated features such as template inheritance, and the need is obviously there as seen in this github issue.
EJS is really ugly and forces you to put too much logic in templates. Jade is cool but forces a completely difference whitespace-based syntax on you, which isn't my style. jinjs is a jinja2 port, but is buggy and abandoned. Most other systems that are similar to jinja2 either lack the specific jinja2 features I want or are hacky and buggy.
jinja2 is a proven, successful templating system. I think javascript needs a robust, feature-complete port of it.
Not yet, but that is coming in the next version.
No, that is not the purpose of this project. There will be subtle differences as documented in the "How is nunjucks different than jinja2" section, and some very obscure features may never be implemented. Additionally, custom filters and tags are not easily available to multiple languages, as they are written specifically in Python or javascript.
It should be very easy. The differences are very small, but they are there. Depending on what features you use, you may need to make small tweaks. The biggest hurdle will be porting any custom filters or tags to javascript.
Read the "How is nunjucks different from jinja2" section for more information on how nunjucks differs from jinja2.
All of the features that will be in v0.1 have been ported over. I am currently testing the codebase and letting it solidify before I make the first release. The focus is now documentation, benchmarks, and tests.
Features needed for v0.1:
Features needed for v0.2:
For now, head over to jinja's documentation for templates. Nunjucks supports most of jinja's features, and those docs are very good. Nunjucks will get better docs over time.
Please read "How Nunjucks is Different from Jinja2" to see what features are missing. Nunjucks is being quickly developed and will implement missing features over time.
This documentation will be improved soon using a documentation generator
Nunjucks borrows a lot of the same concepts from jinja2's API.
An Environment is a central object which handles templates. It is
configurable, specifying how to load and render templates, and which
extensions are available. It is especially important when dealing with
template inheritance, as its used to fetch base templates. (Read more
about the Environment in
jinja2).
The Environment constructor takes an optional list of
loaders. You can pass a single loader or an array of
loaders. Loaders specify how to load templates, whether its from the
file system, a database, or a different source.
var nunjucks = require('nunjucks');
// Without arguments, the environment defaults to a FileSystemLoader
// with the current working directory
var env = new nunjucks.Environment();
// Load templates from the 'templates' folder
var env = new nunjucks.Environment(new nunjucks.FileSystemLoader('templates'));
// The environment will look in templates first and then try loading
// from your special MyLoader class
var env = new nunjucks.Environment([new nunjucks.FileSystemLoader('templates'),
new MyLoader()]);
init(loaders) - Create an Environment object with the template
loaders. loaders can be an array or a single loader. If none is
specified, it defaults to a FileSystemLoader with the current working
directory.
addFilter(name, func) - Register a custom filter
getTemplate(name, eagerCompile) - Get a template. eagerCompile
specifies if it should compile it immediately (defaults to false)
express(app) - Install nunjucks into an express app
A Template is an object that handles the compiling of template
strings and rendering them. The Environment method getTemplate
returns a Template object. You can also create one yourself.
var nunjucks = require('nunjucks');
var tmpl = new nunjucks.Template('Hello {{ username }}');
init(src, env, path, upToDate, eagerCompile) - Create a Template
object. path is a string, upToDate is a function that returns if
the template is up to date or not. eagerCompile tells the template
to compile itself immediately.
render(ctx) - Render a template with the context. ctx is a dict.
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) }}
Currently you cannot create custom tags. This will be easy to do but I want to wait until the parser API stabilizes so that it doesn't change after extensions are created.
FAQs
A powerful templating engine with inheritance, asynchronous control, and more (jinja2 inspired)
The npm package nunjucks receives a total of 934,199 weekly downloads. As such, nunjucks popularity was classified as popular.
We found that nunjucks demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.