{"id":15357167,"url":"https://github.com/chocolateboy/nunjucks-parser","last_synced_at":"2025-04-15T06:43:16.324Z","repository":{"id":48594597,"uuid":"150126500","full_name":"chocolateboy/nunjucks-parser","owner":"chocolateboy","description":"Extract dependencies from nunjucks templates","archived":false,"fork":false,"pushed_at":"2021-07-19T05:29:54.000Z","size":785,"stargazers_count":3,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-15T06:43:10.332Z","etag":null,"topics":["bundler","dependencies","dependency","nunjucks","parcel","parcel-bundler","parser","template"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chocolateboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-24T15:39:30.000Z","updated_at":"2021-11-02T22:20:18.000Z","dependencies_parsed_at":"2022-08-27T21:12:46.564Z","dependency_job_id":null,"html_url":"https://github.com/chocolateboy/nunjucks-parser","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fnunjucks-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fnunjucks-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fnunjucks-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fnunjucks-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chocolateboy","download_url":"https://codeload.github.com/chocolateboy/nunjucks-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249023727,"owners_count":21199958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundler","dependencies","dependency","nunjucks","parcel","parcel-bundler","parser","template"],"created_at":"2024-10-01T12:33:38.973Z","updated_at":"2025-04-15T06:43:16.295Z","avatar_url":"https://github.com/chocolateboy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nunjucks-parser\n\n[![Build Status](https://github.com/chocolateboy/nunjucks-parser/workflows/test/badge.svg)](https://github.com/chocolateboy/nunjucks-parser/actions?query=workflow%3Atest)\n[![NPM Version](https://img.shields.io/npm/v/nunjucks-parser.svg)](https://www.npmjs.org/package/nunjucks-parser)\n\n\u003c!-- TOC --\u003e\n\n- [NAME](#name)\n- [INSTALLATION](#installation)\n- [SYNOPSIS](#synopsis)\n- [DESCRIPTION](#description)\n  - [Why?](#why)\n  - [Why Not?](#why-not)\n- [TYPES](#types)\n  - [Dependency](#dependency)\n  - [Result](#result)\n- [EXPORTS](#exports)\n  - [parseFile](#parsefile)\n  - [parseString](#parsestring)\n  - [renderFile](#renderfile)\n  - [renderString](#renderstring)\n- [DEVELOPMENT](#development)\n- [COMPATIBILITY](#compatibility)\n- [SEE ALSO](#see-also)\n- [VERSION](#version)\n- [AUTHOR](#author)\n- [COPYRIGHT AND LICENSE](#copyright-and-license)\n\n\u003c!-- TOC END --\u003e\n\n# NAME\n\nnunjucks-parser - extract dependencies from nunjucks templates\n\n# INSTALLATION\n\n    $ npm install nunjucks # peer dependency\n    $ npm install nunjucks-parser\n\n# SYNOPSIS\n\n\u003c!-- TOC:ignore --\u003e\n### layout.html\n\n\u003cdetails\u003e\n\n```jinja\n{% include \"components/header.html\" %}\n\u003ch1\u003eHello, world!\u003c/h1\u003e\n{% include \"components/footer.html\" %}\n```\n\n\u003c!-- TOC:ignore --\u003e\n### header.html\n\n```xml\n\u003ch1\u003eHeader\u003c/h1\u003e\n```\n\n\u003c!-- TOC:ignore --\u003e\n### footer.html\n\n```jinja\n\u003ch1\u003eFooter\u003c/h1\u003e\n{% include \"./copyright.txt\" %}\n```\n\n\u003c!-- TOC:ignore --\u003e\n### copyright.txt\n\n```\nCopyright ⓒ example.com 2018\n```\n\n\u003c/details\u003e\n\n\u003c!-- TOC:ignore --\u003e\n### example.js\n\n```javascript\nimport nunjucks      from 'nunjucks'\nimport { parseFile } from 'nunjucks-parser'\n\nconst env = nunjucks.configure('./example')\nconst { content, dependencies } = await parseFile(env, 'layout.html')\n```\n\n\u003c!-- TOC:ignore --\u003e\n### content\n\n```html\n\u003ch1\u003eHeader\u003c/h1\u003e\n\u003ch1\u003eHello, world!\u003c/h1\u003e\n\u003ch1\u003eFooter\u003c/h1\u003e\nCopyright ⓒ example.com 2018\n```\n\n\u003c!-- TOC:ignore --\u003e\n### dependencies\n\n```javascript\n[\n    {\n        name: \"layout.html\",\n        path: \"/home/user/example/layout.html\",\n        parent: null\n    },\n    {\n        name: \"components/header.html\",\n        path: \"/home/user/example/components/header.html\",\n        parent: \"/home/user/example/layout.html\"\n    },\n    {\n        name: \"components/footer.html\",\n        path: \"/home/user/example/components/footer.html\",\n        parent: \"/home/user/example/layout.html\"\n    },\n    {\n        name: \"./copyright.txt\",\n        path: \"/home/user/example/components/copyright.txt\",\n        parent: \"/home/user/example/components/footer.html\"\n    }\n]\n```\n\n# DESCRIPTION\n\nThis module exports [nunjucks](https://mozilla.github.io/nunjucks/) helper\nfunctions which simplify the use of the built-in\n[`Environment#render`](https://mozilla.github.io/nunjucks/api.html#render) and\n[`Environment#renderString`](https://mozilla.github.io/nunjucks/api.html#renderstring)\nfunctions and enhance them to return the template's direct and transitive\ndependencies as well as its rendered content.\n\n## Why?\n\nBundlers such as [Parcel](https://parceljs.org/) provide the ability to track\nasset dependencies so that changes to those dependencies trigger updates in\ntheir dependents. However, nunjucks doesn't provide a built-in way to do this.\n\nThis module provides a simple and efficient way to query this information\nwithout resorting to inefficient workarounds such as monitoring every file in a\ndirectory that has an `.njk` extension. It also provides promisified versions\nof the built-in `render` functions which fix nits and bypass\n[bugs](https://github.com/mozilla/nunjucks/issues/678) in the standard API.\n\n## Why Not?\n\nThis module doesn't provide direct access to a template's AST. Instead, it\nfocuses on exposing the kind of metadata an AST might be queried for (although,\nin the case of dependencies, that data\n[cannot be extracted from the AST](https://github.com/chocolateboy/parcel-plugin-nunjucks/issues/1#issuecomment-423495829)).\nIn the event that you need the actual AST, use nunjucks' parser class.\n\n```javascript\nimport { parser, nodes } from 'nunjucks'\n\nconst src = 'Hello, {{ name }}!'\nconst ast = parser.parse(src)\n\nnodes.printNodes(ast)\n```\n\n# TYPES\n\nThe following types are referenced in the [exports](#exports) below.\n\n## Dependency\n\n```typescript\ntype Dependency = {\n    name: string;\n    path: string;\n    parent: string | null;\n}\n```\n\nEach dependency object contains the following fields:\n\n- name: the dependency's name as it appears in the source\n- path: the dependency's absolute path or URI\n- parent: the resolved path of the dependency's parent file or URI, or null if it doesn't have one\n\n## Result\n\n```typescript\ntype Result = {\n    content: string;\n    dependencies: Array\u003cDependency\u003e;\n}\n```\n\n# EXPORTS\n\n## parseFile\n\n- **Signature**: parseFile (env: [Environment][], templatePath: string, options?: Options) ⇒ Promise\u0026lt;[Result](#result)\u0026gt;\n\n```javascript\nconst { content, dependencies } = await parseFile(env, templatePath, { data })\n```\n\nAn enhanced version of [`renderFile`](#renderfile) which returns the template's\ndependencies as well as its rendered content.\n\nThe following options are supported:\n\n- data (object): an optional value to expose as the template's \"context\"\n\nDependencies are returned in the order in which they're traversed (depth\nfirst), and all descendants are returned, including those that are loaded\ndynamically.\n\nIf deduplicated dependencies are needed, they can be distinguished by the\n`path` property, e.g.:\n\n```javascript\nimport { uniqBy } from 'lodash'\n\nconst deduped = uniqBy(dependencies, 'path')\n```\n\n## parseString\n\n- **Signature**: parseString (env: [Environment][], src: string, options?: Options) ⇒ Promise\u0026lt;[Result](#result)\u0026gt;\n\n```javascript\nconst { content, dependencies } = await parseString(env, src, { data, path })\n```\n\nAn enhanced version of [`renderString`](#renderstring) which returns the\ntemplate's dependencies as well as its rendered content.\n\nIn addition to the options supported by [`parseFile`](#parsefile),\n`parseString` also supports the following options:\n\n- path (string): the optional absolute path/URI of the template: used to resolve relative paths and for error reporting\n\n## renderFile\n\n- **Signature**: renderFile (env: [Environment][], templatePath: string, options?: Options) ⇒ Promise\u0026lt;string\u0026gt;\n\nA version of\n[`Environment#render`](https://mozilla.github.io/nunjucks/api.html#render)\nwhich is (always) async and which is passed its context via an options object.\n\nThe following options are supported:\n\n- data (object): an optional value to expose as the template's \"context\"\n\n## renderString\n\n- **Signature**: renderString (env: [Environment][], src: string, options?: Options) ⇒ Promise\u0026lt;string\u0026gt;\n\nA version of\n[`Environment#renderString`](https://mozilla.github.io/nunjucks/api.html#renderstring)\nwhich is (always) async and which is passed its context and path via an options\nobject.\n\nIn addition to the options supported by [`renderFile`](#renderfile),\n`renderString` also supports the following options:\n\n- path (string): the optional absolute path/URI of the template: used to resolve relative paths and for error reporting\n\n# DEVELOPMENT\n\n\u003cdetails\u003e\n\n\u003c!-- TOC:ignore --\u003e\n## NPM Scripts\n\nThe following NPM scripts are available:\n\n- build - compile the library for testing and save to the target directory\n- build:doc - generate the README's TOC (table of contents)\n- build:release - compile the library for release and save to the target directory\n- clean - remove the target directory and its contents\n- rebuild - clean the target directory and recompile the library\n- test - recompile the library and run the test suite\n- test:run - run the test suite\n\n\u003c/details\u003e\n\n# COMPATIBILITY\n\nThis package is tested and supported on environments which meet the following\nrequirements:\n\n- ES6 Proxy support, e.g.\n  - [Maintained Node.js versions](https://github.com/nodejs/Release#readme)\n  - browsers \u003e IE11\n\n# SEE ALSO\n\n* [nunjucks](https://www.npmjs.com/package/nunjucks)\n* [parcel-plugin-nunjucks](https://www.npmjs.com/package/@chocolateboy/parcel-plugin-nunjucks)\n\n# VERSION\n\n1.1.0\n\n# AUTHOR\n\n[chocolateboy](mailto:chocolate@cpan.org)\n\n# COPYRIGHT AND LICENSE\n\nCopyright © 2018-2020 by chocolateboy.\n\nThis is free software; you can redistribute it and/or modify it under the\nterms of the [Artistic License 2.0](https://www.opensource.org/licenses/artistic-license-2.0.php).\n\n[Environment]: https://mozilla.github.io/nunjucks/api.html#environment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fnunjucks-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchocolateboy%2Fnunjucks-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fnunjucks-parser/lists"}