Skip to content
Parcel support for nunjucks templates
Branch: master
Clone or download
Pull request Compare This branch is 5 commits ahead, 2 commits behind devmattrick:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.editorconfig
.gitignore
CHANGELOG.md
LICENSE
README.md
index.js
package.json
yarn.lock

README.md

parcel-plugin-nunjucks

NPM Version

NAME

parcel-plugin-nunjucks - Parcel support for nunjucks templates

INSTALLATION

$ npm install nunjucks # peer dependency
$ npm install @chocolateboy/parcel-plugin-nunjucks

SYNOPSIS

$ cat src/html/index.njk
{% extends "layout.njk" %}

{% block body %}
    <h1>Hello, {{ name }}!</h1>
{% endblock %}
$ cat nunjucks.config.js
module.exports = {
    root: "./src/html",
    data: { name: process.env.USER },
}
$ parcel build src/html/index.njk

DESCRIPTION

This is a Parcel plugin which uses nunjucks to translate templates with an .njk extension into HTML assets.

As with HTML assets, nunjucks templates can be top-level entries, or dependencies referenced from other documents or templates.

CONFIGURATION

An environment for each (or every) nunjucks template known to Parcel can be configured by creating a nunjucks entry in the project's package.json file, or by exporting a configuration object from one of the following files:

  • nunjucks.config.js
  • .nunjucks.js
  • .nunjucksrc

The configuration object has the following type:

type NunjucksConfiguration = {
    data?:    Object | string => Object;
    env?:     Environment | string => Environment;
    filters?: Object;
    options?: Object;
    root?:    string | Array<string>;
}

Options

The following options can be defined.

data

Data to expose as the "context" in nunjucks assets. Can be defined as a function, in which case it is called with the absolute path/URI of the template being processed and its return value is used as the data.

module.exports = { data: { name: process.env.USER } }

env

The Environment instance to use. Can be defined as a function, in which case it is called with the absolute path/URI of the template being processed and its return value is used as the environment.

const nunjucks = require("nunjucks")
const env = nunjucks.configure("./src/html")

env.addFilter("uc", value => value.toUpperCase())

module.exports = { env }

filters

A map (object) of name/function pairs to add as filters to the environment. Ignored if the env option is supplied.

module.exports = {
    filters: {
        uc: value => value.toUpperCase(),
        lc: value => value.toLowerCase(),
    }
}

options

Options to pass to the nunjucks#configure method, which is used to construct the Environment instance. Ignored if the env option is supplied.

module.exports = {
    options: { noCache: true }
}

root

The base template directory or directories. If not supplied, it defaults to the project root. Ignored if the env option is supplied.

module.exports = { root: "./src/html" }

Note that nunjucks only resolves files in the specified/default template directories, and dies with a misleading error about the file not existing if an attempt is made to access a template outside these directories. This applies to nested template dependencies, but also to top-level entry files i.e. this won't work:

$ cat nunjucks.config.js
module.exports = {
    root: "./src/html",
}
$ parcel ./index.html.njk
# error: ./index.html.njk: template not found: ./index.html.njk

The solution is to add the parent directories of entry files that are nunjucks templates to the list of template directories e.g.:

module.exports = {
    root: ["./src/html", "."],
}
$ parcel ./index.html.njk
# OK

COMPATIBILITY

  • Node.js >= v7.6.0

SEE ALSO

  • nunjucks - a Jinja2-inspired templating engine with support for template inheritance
  • posthtml-extend - a PostHTML plugin which supports Jade-like template inheritance
  • posthtml-include - a PostHTML plugin which supports HTML transclusion

VERSION

2.0.0

AUTHOR

Matthew McCune

This is a fork of the original version by devmattrick, with various fixes and features, since the original appears to be unmaintained.

COPYRIGHT AND LICENSE

Copyright © 2017-2018 by Matthew McCune.

This is free software; you can redistribute it and/or modify it under the terms of the MIT license.

You can’t perform that action at this time.