README

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

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

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

@chocolateboy/parcel-plugin-nunjucksdeprecated

Usage no npm install needed!