# gulp-nunjucks

> Compile/precompile Nunjucks templates

Latest version **6.1.0** (published 2025-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-nunjucks
pnpm add gulp-nunjucks
yarn add gulp-nunjucks
bun add gulp-nunjucks
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.1.0 |
| Published | 2025-09-14 |
| First published | 2013-12-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 8.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 153 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | gulpplugin, nunjucks, jinja, jinja2, django, template, templating, view, precompile, compile, html, javascript |

## Links

- npm: https://www.npmjs.com/package/gulp-nunjucks
- Repository: https://github.com/sindresorhus/gulp-nunjucks
- Homepage: https://github.com/sindresorhus/gulp-nunjucks#readme
- Issues: https://github.com/sindresorhus/gulp-nunjucks/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/gulp-nunjucks

## Dependencies (2)

- [nunjucks](https://npm.io/package/nunjucks.md) ^3.2.4
- [gulp-plugin-extras](https://npm.io/package/gulp-plugin-extras.md) ^0.2.2

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 6.1.0 (latest) — 2025-09-14
- 6.0.0 — 2023-11-02
- 5.1.0 — 2020-09-29
- 5.0.2 — 2020-09-10
- 5.0.1 — 2019-10-04
- 5.0.0 — 2019-05-28
- 4.0.0 — 2018-05-04
- 3.1.1 — 2018-01-02
- 3.1.0 — 2017-12-31
- 3.0.0 — 2017-01-05
- 2.3.0 — 2016-09-22
- 2.2.0 — 2016-02-18
- 2.1.1 — 2016-01-13
- 2.1.0 — 2015-12-29
- 2.0.0 — 2015-09-10
- … 9 more at https://npm.io/package/gulp-nunjucks/versions

## README

# gulp-nunjucks

> Compile/precompile [Nunjucks](https://mozilla.github.io/nunjucks/) templates

*Issues with the output should be reported on the Nunjucks [issue tracker](https://github.com/mozilla/nunjucks/issues).*

## Install

```sh
npm install --save-dev gulp-nunjucks
```

## Usage

### Compile

```js
import gulp from 'gulp';
import {nunjucksCompile} from 'gulp-nunjucks';

export default () => (
	gulp.src('templates/greeting.html')
		.pipe(nunjucksCompile({name: 'Sindre'}))
		.pipe(gulp.dest('dist'))
);
```

You can alternatively use [gulp-data](https://github.com/colynb/gulp-data) to inject the data:

```js
import gulp from 'gulp';
import {nunjucksCompile} from 'gulp-nunjucks';
import data from 'gulp-data';

export default () => (
	gulp.src('templates/greeting.html')
		.pipe(data(() => ({name: 'Sindre'})))
		.pipe(nunjucksCompile())
		.pipe(gulp.dest('dist'))
);
```

### Precompile

```js
import gulp from 'gulp';
import {nunjucksPrecompile} from 'gulp-nunjucks';

export default () => (
	gulp.src('templates/greeting.html')
		.pipe(nunjucksPrecompile())
		.pipe(gulp.dest('dist'))
);
```

## API

### nunjucksCompile(data?, options?)

Compile a template using the provided `data`.

#### data

Type: `object`

The data object used to populate the text.

#### options

Type: `object`

Options will be passed directly to the Nunjucks [Environment constructor](https://mozilla.github.io/nunjucks/api.html#constructor) which will be used to compile templates.

##### options.env

Type: `nunjucks.Environment`\
Default: `new nunjucks.Environment()`

The custom Nunjucks [Environment object](https://mozilla.github.io/nunjucks/api.html#environment) which will be used to compile templates. If supplied, the rest of `options` will be ignored.

##### options.filters

Type: `object`

An object containing [custom filters](https://mozilla.github.io/nunjucks/api.html#custom-filters) that will be passed to Nunjucks, with the filter's name as key and the filter function as value.

Async filters should be defined as async functions. You cannot use just a promise-returning function.

```js
{
	'shorten': string => string.slice(0, 5),
	'round': number => Math.round(number),
	'fetch': async url => {
		const response = await fetch(url);
		const result = await response.text();
		return result;
	}
}
```

##### options.extensions

Type: `object`

An object containing [custom tags/extensions](https://mozilla.github.io/nunjucks/api.html#custom-tags) that will be passed to Nunjucks, with the extension's name as key and the extension instance as value.

```js
{
	'UppercaseExtension': new UppercaseExtension()
}
```

### nunjucksPrecompile(options?)

Precompile a template for rendering dynamically at a later time.

Same options as [`nunjucks.precompile()`](https://mozilla.github.io/nunjucks/api.html#precompile) except for `name`.

#### options

Type: `object`

##### name

Type: `Function`\
Default: Relative template path\
Example: `templates/list.html`

You can override the default behavior by supplying a function which gets the current [File](https://github.com/gulpjs/vinyl#options) object and is expected to return the name.

Example:

```js
{
	name: file => `template-${file.relative}`
}
```

---
_Source: https://npm.io/package/gulp-nunjucks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._