- NAME
- INSTALLATION
- SYNOPSIS
- DESCRIPTION
- TYPES
- EXPORTS
- DEVELOPMENT
- COMPATIBILITY
- SEE ALSO
- VERSION
- AUTHOR
- COPYRIGHT AND LICENSE
nunjucks-parser - extract dependencies from nunjucks templates
$ npm install nunjucks # peer dependency
$ npm install nunjucks-parser
{% include "components/header.html" %}
<h1>Hello, world!</h1>
{% include "components/footer.html" %}<h1>Header</h1><h1>Footer</h1>
{% include "./copyright.txt" %}Copyright ⓒ example.com 2018
import nunjucks from 'nunjucks'
import { parseFile } from 'nunjucks-parser'
const env = nunjucks.configure('./example')
const { content, dependencies } = await parseFile(env, 'layout.html')<h1>Header</h1>
<h1>Hello, world!</h1>
<h1>Footer</h1>
Copyright ⓒ example.com 2018[
{
name: "layout.html",
path: "/home/user/example/layout.html",
parent: null
},
{
name: "components/header.html",
path: "/home/user/example/components/header.html",
parent: "/home/user/example/layout.html"
},
{
name: "components/footer.html",
path: "/home/user/example/components/footer.html",
parent: "/home/user/example/layout.html"
},
{
name: "./copyright.txt",
path: "/home/user/example/components/copyright.txt",
parent: "/home/user/example/components/footer.html"
}
]This module exports nunjucks helper
functions which simplify the use of the built-in
Environment#render and
Environment#renderString
functions and enhance them to return the template's direct and transitive
dependencies as well as its rendered content.
Bundlers such as Parcel provide the ability to track asset dependencies so that changes to those dependencies trigger updates in their dependents. However, nunjucks doesn't provide a built-in way to do this.
This module provides a simple and efficient way to query this information
without resorting to inefficient workarounds such as monitoring every file in a
directory that has an .njk extension. It also provides promisified versions
of the built-in render functions which fix nits and bypass
bugs in the standard API.
This module doesn't provide direct access to a template's AST. Instead, it focuses on exposing the kind of metadata an AST might be queried for (although, in the case of dependencies, that data cannot be extracted from the AST). In the event that you need the actual AST, use nunjucks' parser class.
import { parser, nodes } from 'nunjucks'
const src = 'Hello, {{ name }}!'
const ast = parser.parse(src)
nodes.printNodes(ast)The following types are referenced in the exports below.
type Dependency = {
name: string;
path: string;
parent: string | null;
}Each dependency object contains the following fields:
- name: the dependency's name as it appears in the source
- path: the dependency's absolute path or URI
- parent: the resolved path of the dependency's parent file or URI, or null if it doesn't have one
type Result = {
content: string;
dependencies: Array<Dependency>;
}- Signature: parseFile (env: Environment, templatePath: string, options?: Options) ⇒ Promise<Result>
const { content, dependencies } = await parseFile(env, templatePath, { data })An enhanced version of renderFile which returns the template's
dependencies as well as its rendered content.
The following options are supported:
- data (object): an optional value to expose as the template's "context"
Dependencies are returned in the order in which they're traversed (depth first), and all descendants are returned, including those that are loaded dynamically.
If deduplicated dependencies are needed, they can be distinguished by the
path property, e.g.:
import { uniqBy } from 'lodash'
const deduped = uniqBy(dependencies, 'path')- Signature: parseString (env: Environment, src: string, options?: Options) ⇒ Promise<Result>
const { content, dependencies } = await parseString(env, src, { data, path })An enhanced version of renderString which returns the
template's dependencies as well as its rendered content.
In addition to the options supported by parseFile,
parseString also supports the following options:
- path (string): the optional absolute path/URI of the template: used to resolve relative paths and for error reporting
- Signature: renderFile (env: Environment, templatePath: string, options?: Options) ⇒ Promise<string>
A version of
Environment#render
which is (always) async and which is passed its context via an options object.
The following options are supported:
- data (object): an optional value to expose as the template's "context"
- Signature: renderString (env: Environment, src: string, options?: Options) ⇒ Promise<string>
A version of
Environment#renderString
which is (always) async and which is passed its context and path via an options
object.
In addition to the options supported by renderFile,
renderString also supports the following options:
- path (string): the optional absolute path/URI of the template: used to resolve relative paths and for error reporting
The following NPM scripts are available:
- build - compile the library for testing and save to the target directory
- build:doc - generate the README's TOC (table of contents)
- build:release - compile the library for release and save to the target directory
- clean - remove the target directory and its contents
- rebuild - clean the target directory and recompile the library
- test - recompile the library and run the test suite
- test:run - run the test suite
This package is tested and supported on environments which meet the following requirements:
- ES6 Proxy support, e.g.
- Maintained Node.js versions
- browsers > IE11
1.1.0
Copyright © 2018-2020 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.