Skip to content

Latest commit

 

History

History
254 lines (174 loc) · 8.11 KB

README.md

File metadata and controls

254 lines (174 loc) · 8.11 KB
Raw

nunjucks-parser

Build Status NPM Version

NAME

nunjucks-parser - extract dependencies and other metadata from nunjucks templates

INSTALLATION

$ npm install nunjucks nunjucks-parser

SYNOPSIS

layout.html

{% include "components/header.html" %}
<h1>Body</h1>
{% include "components/footer.html" %}

header.html

<h1>Header</h1>

footer.html

<h1>Footer</h1>
{% include "./copyright.html" %}

copyright.html

Copyright ⓒ example.com 2018

test.js

import nunjucks      from 'nunjucks'
import { parseFile } from 'nunjucks-parser'

const env = nunjucks.configure('example')
const { content, template, dependencies } = await parseFile(env, 'layout.html')

console.log(dependencies)

result

[
    {
        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.html",
        path: "/home/user/example/components/copyright.html",
        parent: "/home/user/example/components/footer.html"
    }
]

DESCRIPTION

This module exports a pair of nunjucks helper functions, parseFile and parseString, which function like enhanced versions of the built-in Environment#render and Environment#renderString methods.

In addition to always returning promises — which, amongst other things, sidesteps a bug in the synchronous API which silently swallows errors — these methods also return more data than the render methods i.e.:

  • content (string): the rendered template string
  • template (Template): the Template instance used to render the template
  • dependencies (Array<Object>): an array of objects representing the direct and transitive dependencies reachable from the template

Each dependency object contains the following fields:

  • name (string): the template's name as it appears in the source (may have been resolved to an absolute path/URI if it's relative)
  • parent (string|null): null if the dependency has no parent file; otherwise the resolved path of its parent file
  • path (string): the resolved path of this dependency (child template)

Why?

Bundlers such as Parcel provide the ability to track the direct and transitive dependencies of assets so that changes to those dependencies trigger updates in their dependents. nunjucks doesn't provide a built-in way to do this, so this functionality must currently be done in a non-optimal way e.g. by monitoring every file in a directory that has an .njk extension.

This package provides an easy way to retrieve a template's dependencies. In addition, it exposes some other metadata that is not exposed by the built-in render and renderString methods.

Why Not?

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 particular 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)

EXPORTS

parseFile

Signature: parseFile(env: Environment, templatePath: string, options?: Object) -> Promise<Object>

const { content, template, dependencies } = await parseFile(env, templatePath, { data })

An enhanced version of renderFile which augments its result with an array of objects representing the template's dependencies.

The following options are supported:

  • data (Object): an optional value to expose as the template's "context"

parseString

Signature: parseString(env: Environment, src: string, options?: Object) -> Promise<Object>

const { content, template, dependencies } = await parseString(env, src, { data, path })

An enhanced version of renderString which augments its result with an array of objects representing the template's dependencies.

The following options are supported:

  • data (Object): an optional value to expose as the template's "context"
  • path (string): an optional path/URL for the template: used to resolve file-relative paths and for error reporting

renderFile

Signature: renderFile(env: Environment, src: string, options?: Object) -> Promise<Object>

const { content, template } = await renderFile(env, src, { data })

A promisified variant of Environment#render which yields the resulting Template object (template) as well as its rendered string (content).

The following options are supported:

  • data (Object): an optional value to expose as the template's "context"

renderString

Signature: renderString(env: Environment, src: string, options?: Object) -> Promise<Object>

const { content, template } = await renderString(env, src, { data })

A promisified variant of Environment#renderString which yields the resulting Template object (template) as well as its rendered string (content).

The following options are supported:

  • data (Object): an optional value to expose as the template's "context"

DEVELOPMENT

NPM Scripts

The following NPM scripts are available:

  • build - compile a production build of the library and save it to the target directory
  • build:dev - compile a development build of the library and save it to the target directory
  • clean - remove the target directory and its contents
  • test - compile the library and run the test suite

COMPATIBILITY

This package is tested and supported on environments which meet the following requirements:

  • ES6 Proxy support e.g.
    • Node >= v6.0
    • browsers > IE11

SEE ALSO

VERSION

0.0.1

AUTHOR

chocolateboy

COPYRIGHT AND LICENSE

Copyright © 2018 by chocolateboy.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.