express-nunjucks

Is the glue for express and nunjucks.

Features

• Easy connection.
• Uses of common templates, filters and extensions.
• Uses an asynchronous loader templates nunjucks-async-loader.
• Support context processors.

Installation

$ npm install nunjucks express-nunjucks --save

Usage

const express = require('express');
const expressNunjucks = require('express-nunjucks');
const app = express();
const isDev = app.get('env') === 'development';

app.set('views', __dirname + '/templates');

const njk = expressNunjucks(app, {
    watch: isDev,
    noCache: isDev
});

app.get('/', (req, res) => {
    res.render('index');
});

app.listen(3000);

API

expressNunjucks(apps [,config]) -> njk

apps {Object|Array}

Express application or an array of applications.

config {Object}

• watch=false {Boolean} - if true, the system will automatically update templates when they are changed on the filesystem.
• noCache=false {Boolean} - if true, the system will avoid using a cache and templates will be recompiled every single time.
• autoescape=true {Boolean} - controls if output with dangerous characters are escaped automatically.
• throwOnUndefined=false {Boolean} - throw errors when outputting a null/undefined value.
• trimBlocks=false {Boolean} - automatically remove trailing newlines from a block/tag.
• lstripBlocks=false {Boolean} - automatically remove leading whitespace from a block/tag.
• tags - defines the syntax for nunjucks tags.
• filters - defines the syntax for nunjucks filters.
• loader - defines loader templates. The default is the asynchronous loader templates.
• globals - defines global variables.

njk.ctxProc(ctxProcessors) -> Middleware

Creates Express middleware to work context processors.

njk.env -> Environment

Returns Nunjucks Environment.

Examples

Use filters

Create custom filters in nunjucks.

const express = require('express');
const expressNunjucks = require('express-nunjucks');
const filters = require('./filters');

const app = express();

app.set('views', __dirname + '/templates');

const njk = expressNunjucks(app, {
    // Add custom filter.
    filters: filters
});

app.get('/', (req, res) => {
    res.render('index');
});

app.listen(3000);

Use globals

Defines globals to use this in templates.

const express = require('express');
const expressNunjucks = require('express-nunjucks');
const asset = require('./utils').asset;

const app = express();

app.set('views', __dirname + '/templates');

const njk = expressNunjucks(app, {
    // Defines globals.
    globals: {asset: asset}
});

app.get('/', (req, res) => {
    res.render('index');
});

app.listen(3000);

...
<link rel="stylesheet" href="{{ asset('styles.css') }}">
...

Use context processors

Context processors is one great idea from the django framework.

const express = require('express');
const expressNunjucks = require('express-nunjucks');
const webpackAssets = require('./build/assets');

const app = express();

app.set('views', __dirname + '/templates');

// Adds information about the request in the context of the template.
const reqCtxProcessor = (req, ctx) => {
    ctx.req = req;
};
// Adds links to statics in the context of the template.
const assetsCtxProcessor = (req, ctx) => {
    ctx.scripts = webpackAssets.scripts;
    ctx.styles = webpackAssets.styles;
};

const njk = expressNunjucks(app);

app.use(njk.ctxProc([
    reqCtxProcessor,
    assetsCtxProcessor    
]));

app.get('/', (req, res) => {
    res.render('index');
});

app.listen(3000);

Warning! Context processors not supported to app.render().

Use synchronous loader templates

const express = require('express');
const expressNunjucks = require('express-nunjucks');

const app = express();

app.set('views', __dirname + '/templates');

const njk = expressNunjucks(app, {
    loader: nunjucks.FileSystemLoader
});

app.get('/', (req, res) => {
    res.render('index');
});

app.listen(3000);

Use application and sub application

General application

// proj/app.js

const express = require('express');
const expressNunjucks = require('express-nunjucks');
const subApp = require('./subapp');

const app = express();

app.set('views', __dirname + '/templates');

const njk = expressNunjucks([app, subApp]);

app.get('/', (req, res) => {
    res.render('index');
});

app.use('/subApp', subApp);
// and more...

app.listen(3000);

Sub application

// proj/subapp/index.js

const express = require('express');
const app = express();

app.set('views', __dirname + '/templates');

app.get('/', (req, res) => {
    res.render('index');
});

module.exports = app;

Template hierarchy

proj
|
|- templates
|   |
|   |- base.html
|   |- index.html
|   |-subapp
|      |
|      |-page.html
|
|- subapp
    |
    |-templates
       |
       |-subapp
          |
          |-index.html
          |-page.html

The templates in the directory proj/templates/subapp override templates proj/subapp/templates/subapp.

Tests

To run the test suite, first install the dependencies, then run npm test:

$ npm install
$ npm test

License

MIT