{"id":13782363,"url":"https://github.com/chocolateboy/parcel-plugin-nunjucks","last_synced_at":"2025-10-23T15:30:54.409Z","repository":{"id":27637531,"uuid":"114720820","full_name":"chocolateboy/parcel-plugin-nunjucks","owner":"chocolateboy","description":"Parcel support for nunjucks templates","archived":false,"fork":false,"pushed_at":"2023-01-06T02:01:57.000Z","size":2360,"stargazers_count":50,"open_issues_count":14,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-30T19:11:19.402Z","etag":null,"topics":["nunjucks","parcel","parcel-bundler","parcel-plugin","plugin","template","templates"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","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","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-19T04:57:10.000Z","updated_at":"2023-09-01T13:48:00.000Z","dependencies_parsed_at":"2023-01-14T07:10:43.762Z","dependency_job_id":null,"html_url":"https://github.com/chocolateboy/parcel-plugin-nunjucks","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fparcel-plugin-nunjucks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fparcel-plugin-nunjucks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fparcel-plugin-nunjucks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fparcel-plugin-nunjucks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chocolateboy","download_url":"https://codeload.github.com/chocolateboy/parcel-plugin-nunjucks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237843917,"owners_count":19375230,"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":["nunjucks","parcel","parcel-bundler","parcel-plugin","plugin","template","templates"],"created_at":"2024-08-03T18:01:35.779Z","updated_at":"2025-10-23T15:30:49.087Z","avatar_url":"https://github.com/chocolateboy.png","language":"JavaScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Templates"],"readme":"# parcel-plugin-nunjucks\n\n[![Build Status](https://github.com/chocolateboy/parcel-plugin-nunjucks/workflows/test/badge.svg)](https://github.com/chocolateboy/parcel-plugin-nunjucks/actions?query=workflow%3Atest)\n[![NPM Version](https://img.shields.io/npm/v/parcel-plugin-nunjucks.svg)](https://www.npmjs.org/package/parcel-plugin-nunjucks)\n\n\u003c!-- TOC --\u003e\n\n- [NAME](#name)\n- [INSTALLATION](#installation)\n- [SYNOPSIS](#synopsis)\n- [DESCRIPTION](#description)\n- [CONFIGURATION](#configuration)\n  - [Type](#type)\n  - [Path parameter](#path-parameter)\n  - [Options](#options)\n    - [assetType](#assettype)\n      - [Raw assets](#raw-assets)\n    - [data](#data)\n    - [env](#env)\n    - [filters](#filters)\n    - [options](#options-1)\n    - [root](#root)\n- [DEVELOPMENT](#development)\n- [COMPATIBILITY](#compatibility)\n- [SEE ALSO](#see-also)\n- [VERSION](#version)\n- [AUTHORS](#authors)\n- [COPYRIGHT AND LICENSE](#copyright-and-license)\n\n\u003c!-- TOC END --\u003e\n\n# NAME\n\nparcel-plugin-nunjucks - [Parcel](https://parceljs.org/) support for [nunjucks](https://mozilla.github.io/nunjucks/) templates\n\n# INSTALLATION\n\n    $ npm install nunjucks # peer dependency\n    $ npm install parcel-plugin-nunjucks\n\n# SYNOPSIS\n\n```\n$ cat src/html/index.njk\n```\n\n```jinja\n{% extends 'layout.njk' %}\n\n{% block body %}\n    \u003ch1\u003eHello, {{ name }}!\u003c/h1\u003e\n{% endblock %}\n```\n\n```\n$ cat nunjucks.config.js\n```\n\n```javascript\nmodule.exports = {\n    root: './src/html',\n    data: { name: process.env.USER },\n}\n```\n\n```\n$ parcel build src/html/index.njk\n```\n\n# DESCRIPTION\n\nThis is a Parcel plugin which uses nunjucks to translate templates with an\n`.njk` extension into Parcel assets.\n\nAs with other asset types, nunjucks templates can be top-level\n[entries](#root), or dependencies referenced from other documents or templates.\n\n# CONFIGURATION\n\nAn [environment](https://mozilla.github.io/nunjucks/api.html#environment) for\nany (or every) nunjucks template known to Parcel can be configured by creating\na `nunjucks` entry in the project's `package.json` file, or by exporting\n(CommonJS) or defining (JSON) a configuration object in one of the following\nfiles:\n\n- `.nunjucksrc` (JSON)\n- `.nunjucks.js`\n- `nunjucks.config.js`\n\n## Type\n\nThe configuration object has the following type:\n\n```typescript\ninterface AssetType {\n    value?: false | string;\n    raw?: boolean;\n}\n\ninterface NunjucksConfiguration {\n    assetType?: false | string | AssetType | ((path: Path) =\u003e (false | string | AssetType));\n    data?:      object | ((path: Path) =\u003e (object | PromiseLike\u003cobject\u003e));\n    env?:       Nunjucks.Environment | ((path: Path) =\u003e Nunjucks.Environment);\n    filters?:   { [name: string]: Function };\n    options?:   Nunjucks.ConfigureOptions;\n    root?:      string | string[];\n}\n```\n\n## Path parameter\n\nOptions that are defined as functions ([`assetType`](#assettype),\n[`data`](#data), and [`env`](#env)) are passed an object containing the parsed\ncomponents of the template's absolute path (including the path itself) as a\nparameter, e.g. if the path is `/foo/bar/baz.html.njk`, the parameter would\ncontain the following fields:\n\n```javascript\n{\n    baseExt:  '.html',\n    basePath: '/foo/bar/baz.html',\n    dir:      '/foo/bar',\n    dirname:  'bar',\n    dirs:     ['', 'foo', 'bar'],\n    ext:      '.njk',\n    filename: 'baz.html.njk',\n    name:     'baz.html',\n    path:     '/foo/bar/baz.html.njk',\n    root:     '/',\n}\n```\n\n## Options\n\nThe following options can be defined.\n\n### assetType\n\nOverride a template's type within Parcel. This allows the rendered template to\nbe processed as a file of the specified type, e.g. a HTML template will be\nscanned for links to scripts, stylesheets etc., and a templated JavaScript file\nwill be scanned for `require`s and `import`s etc.\n\nDefined as a falsey value (the default), a string, or an object, or can be\ndefined as a function, in which case it is called with an object containing the\npath of the template being processed (see [Path parameter](#path-parameter)),\nand its return value is used as the asset type.\n\nBy default, each template's type is determined by the extension before the\n`.njk` suffix, defaulting to HTML if there isn't one or if the extension isn't\nrecognized, e.g.:\n\n| filename         | type       |\n|------------------|------------|\n| `index.html.njk` | HTML       |\n| `index.js.njk`   | JavaScript |\n| `index.css.njk`  | CSS        |\n| `index.njk`      | HTML       |\n| `page-1.0.njk`   | HTML       |\n\nThis behavior can be overridden by setting the `assetType` option. The default\nvalue is falsey, which enables the filename-matching behavior. Setting it to a\nstring makes the value the type for all `.njk` files, e.g. setting it to `html`\nmakes all files HTML regardless of the filename (which was the default in\nparcel-plugin-nunjucks v1):\n\n```javascript\nmodule.exports = {\n    data: { ... },\n    assetType: 'html',\n}\n```\n\nThe supported types are the extensions registered with Parcel, including those\nregistered by plugins, and they typically correspond to the standard extensions\nfor the respective filetypes, e.g.:\n\n| extension  | type       |\n| ---------- | ---------- |\n| css        | CSS        |\n| htm/html   | HTML       |\n| js         | JavaScript |\n| ts         | TypeScript |\n\nThe type can be written with or without the leading dot, e.g. `html` and `.html`\nare equivalent.\n\nAs an example, the following configuration assigns the default type(s) to most\nfiles, but overrides the type for files in `src/js` and `src/css`. This allows\nthe latter to be output as e.g. `foo.html`, `bar.js`, `baz.css` etc. rather\nthan `foo.html.html`, `bar.js.js`, `baz.css.css` etc.\n\n```javascript\n// if there's no base extension, infer the asset type from the name of the\n// containing directory, e.g.:\n//\n//   - foo.html.njk    → html\n//   - bar.js.njk      → js\n//   - baz.css.njk     → css\n//   - src/js/foo.njk  → js\n//   - src/css/bar.njk → css\n//\nmodule.exports = {\n    assetType ({ baseExt, dirname }) {\n        return baseExt || dirname\n    }\n}\n```\n\n#### Raw assets\n\nBy default, nunjucks assets are processed as the specified or inferred\nasset-type i.e. they're scanned and transformed in the same way as regular\nJavaScript/HTML etc. files. In some cases, it may be preferable to specify a\nrendered template's target type/extension (e.g. HTML) without processing it as\nthat type (e.g. with PostHTML). This can be done by supplying the `assetType`\noption as an [object](#type) rather than a string, and setting\nits `raw` property to true, e.g.:\n\n```javascript\nmodule.exports = {\n    data: { ... },\n    assetType: { value: 'html', raw: true },\n}\n```\n\nIf not supplied, the `raw` property defaults to false. As with the non-object\nshorthand, the `value` property can be falsey (infer the type from the\nfilename) or a type name (string), e.g. `html` or `.js`.\n\n### data\n\nData to expose as the \"context\" in nunjucks\n[assets](https://parceljs.org/assets.html). Can be defined as a function, in\nwhich case it is called with an object containing the path of the template\nbeing processed (see [Path parameter](#path-parameter)), and its return value\n(which can be a promise if the data is loaded asynchronously) is used as the\ndata.\n\n```javascript\nmodule.exports = {\n    data: { name: process.env.USER }\n}\n\n// or\n\nasync function getData ({ filename }) {\n    const data = await http.getData()\n    return { filename, ...data }\n}\n\nmodule.exports = { data: getData }\n```\n\n### env\n\nThe [Environment](https://mozilla.github.io/nunjucks/api.html#environment)\ninstance to use. Can be defined as a function, in which case it is called with\nan object containing the path of the template being processed (see\n[Path parameter](#path-parameter)), and its return value is used as the\nenvironment.\n\n```javascript\nconst Nunjucks = require('nunjucks')\nconst env = Nunjucks.configure('./src/html')\n\nenv.addFilter('uc', value =\u003e value.toUpperCase())\n\nmodule.exports = { env }\n```\n\n### filters\n\nA map (object) of name/function pairs to add as filters to the environment.\nIgnored if the `env` option is supplied.\n\n```javascript\nmodule.exports = {\n    filters: {\n        uc: value =\u003e value.toUpperCase(),\n        lc: value =\u003e value.toLowerCase(),\n    }\n}\n```\n\n### options\n\nOptions to pass to the\n[`nunjucks#configure`](https://mozilla.github.io/nunjucks/api.html#configure)\nmethod, which is used to construct the Environment instance. Ignored if the\n`env` option is supplied.\n\n```javascript\nmodule.exports = {\n    options: { autoescape: false }\n}\n```\n\n### root\n\nThe base template directory or directories. Can be a single path (string) or\nmultiple paths (array of strings). If not supplied, it defaults to the current\ndirectory (`.`). Ignored if the `env` option is supplied.\n\nRelative paths are resolved against the directory of the configuration file in\nwhich the paths are defined (or the `package.json` if defined there), falling\nback to the current working directory if a configuration file isn't found.\n\n```javascript\nmodule.exports = { root: './src/html' }\n```\n\nNote that nunjucks only resolves files in the specified/default template\ndirectories, and dies with a misleading error about the file not existing if an\nattempt is made to access a template outside these directories. This applies to\nnested template dependencies, but also to top-level entry files i.e. this won't\nwork:\n\n```javascript\nmodule.exports = {\n    root: './src/html',\n}\n```\n\n```\n$ parcel ./index.html.njk\n# error: ./index.html.njk: template not found: ./index.html.njk\n```\n\nThe solution is to add the parent directories of entry files that are nunjucks\ntemplates to the list of template directories, e.g.:\n\n```javascript\nmodule.exports = {\n    root: ['./src/html', '.'],\n}\n```\n\n```\n$ parcel ./index.html.njk\n# OK\n```\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 code and save it to the `dist` directory\n- build:doc - generate the README's TOC (table of contents)\n- clean - remove the `dist` directory and other build artifacts\n- rebuild - clean the build artifacts and recompile the code\n- test - clean and rebuild and run the test suite\n- test:run - run the test suite\n\n\u003c/details\u003e\n\n# COMPATIBILITY\n\n* [Maintained Node.js versions](https://github.com/nodejs/Release#readme)\n\n# SEE ALSO\n\n* [nunjucks](https://www.npmjs.com/package/nunjucks) - a Jinja2-inspired templating engine with support for template inheritance\n* [posthtml-extend](https://www.npmjs.com/package/posthtml-extend) - a PostHTML plugin which supports Jade-like template inheritance\n* [posthtml-include](https://www.npmjs.com/package/posthtml-include) - a PostHTML plugin which supports HTML transclusion\n\n# VERSION\n\n2.2.2\n\n# AUTHORS\n\n- [chocolateboy](mailto:chocolate@cpan.org)\n- [Matthew McCune](mailto:matthew@matthew.cx) (original version)\n\n# COPYRIGHT AND LICENSE\n\nCopyright © 2017-2020 by Matthew McCune.\n\nThis is free software; you can redistribute it and/or modify it under the\nterms of the [MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fparcel-plugin-nunjucks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchocolateboy%2Fparcel-plugin-nunjucks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fparcel-plugin-nunjucks/lists"}