npm

npm’s 2019 JavaScript ecosystem survey analysis is now available!Get your copy here »

@chocolateboy/parcel-plugin-nunjucks

2.0.0 • Public • Published

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.

install

npm i @chocolateboy/parcel-plugin-nunjucks

Downloadsweekly downloads

0

version

2.0.0

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability