‚̧Noiseless Praying Mantis
    Have ideas to improve npm?Join in the discussion! ¬Ľ

    nunjucks-parser

    1.1.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    nunjucks-parser

    Build Status NPM Version

    NAME

    nunjucks-parser - extract dependencies from nunjucks templates

    INSTALLATION

    $ npm install nunjucks # peer dependency
    $ npm install nunjucks-parser
    

    SYNOPSIS

    layout.html

    {% include "components/header.html" %}
    <h1>Hello, world!</h1>
    {% include "components/footer.html" %}

    header.html

    <h1>Header</h1>

    footer.html

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

    copyright.txt

    Copyright ‚ďí example.com 2018
    

    example.js

    import nunjucks      from 'nunjucks'
    import { parseFile } from 'nunjucks-parser'
     
    const env = nunjucks.configure('./example')
    const { content, dependencies } = await parseFile(env, 'layout.html')

    content

    <h1>Header</h1>
    <h1>Hello, world!</h1>
    <h1>Footer</h1>
    Copyright¬†‚ďí¬†example.com¬†2018

    dependencies

    [
        {
            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"
        }
    ]

    DESCRIPTION

    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.

    Why?

    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.

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

    TYPES

    The following types are referenced in the exports below.

    Dependency

    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

    Result

    type Result = {
        content: string;
        dependencies: Array<Dependency>;
    }

    EXPORTS

    parseFile

    Signature: parseFile(env: Environment, templatePath: string, options?: Object) ‚Üí 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')

    parseString

    Signature: parseString(env: Environment, src: string, options?: Object) ‚Üí 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

    renderFile

    Signature: renderFile(env: Environment, templatePath: string, options?: Object) ‚Üí 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"

    renderString

    Signature: renderString(env: Environment, src: string, options?: Object) ‚Üí 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

    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:

    SEE ALSO

    VERSION

    1.1.0

    AUTHOR

    chocolateboy

    COPYRIGHT AND LICENSE

    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.

    Install

    npm i nunjucks-parser

    DownloadsWeekly Downloads

    603

    Version

    1.1.0

    License

    Artistic-2.0

    Unpacked Size

    38.4 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar