@chocolateboy/parcel-plugin-nunjucks

parcel-plugin-nunjucks

• NAME
• INSTALLATION
• SYNOPSIS
• DESCRIPTION
• CONFIGURATION
  • Options
    • data
    • env
    • filters
    • options
    • root
• COMPATIBILITY
• SEE ALSO
• VERSION
• AUTHOR
• COPYRIGHT AND LICENSE

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.