prettier-plugin-nunjucks weekly downloads statistics

prettier-plugin-nunjucks

Prettier plugin for HTML-heavy Nunjucks templates.

It formats .njk / .nunjucks / .nunj files with stable, idempotent output and keeps Nunjucks statement tags, variables, comments, whitespace-control markers, and raw/verbatim blocks in the Nunjucks syntax instead of treating them as Handlebars or generic HTML.

Install

Quick Start

Recommended config:

The explicit override makes editor format-on-save deterministic, especially in projects that mix HTML, Nunjucks, Jinja-like templates, and other Prettier plugins.

Configuration Patterns

1. Minimal plugin setup

Use this only after verifying your Prettier/editor resolves .njk files to this plugin.

2. Explicit Nunjucks override

Use this for shared projects and CI.

3. Projects with Nunjucks in HTML files

If your project stores Nunjucks templates as .html, force the parser for those paths.

4. Project style options

Normal Prettier options still apply.

5. Local plugin path during dogfooding

Useful before publishing a new npm version.

Text wrapping

Normal HTML text wraps at word boundaries to respect printWidth, including the available width after indentation. Nunjucks variables stay intact, and words or punctuation glued to them stay glued. proseWrap does not control HTML text wrapping, just as with Prettier's HTML printer.

printWidth is a target, not a hard limit: unbreakable words, template expressions, and whitespace-sensitive content such as pre, textarea, and raw/verbatim blocks may remain longer than it.

Text and inline variables wrap as one text flow inside HTML block elements such as p and div, Nunjucks block bodies, and the template root. Configured inlineTags participate in the same flow. Existing line breaks in ordinary text do not force variables onto separate lines or disable wrapping. Actual inline HTML elements such as a and span retain their significant tag boundaries.

classAttributeLayout

Control whether class attribute values may use multiple physical lines. The default auto mode preserves the existing formatting rules. Use single-line to keep static and conditional class values on one line; the surrounding HTML tag may still wrap.

| Default | CLI Override | API Override |

| "auto" | --class-attribute-layout | classAttributeLayout: "auto" \| "single-line" |

Custom extension tags

Nunjucks extensions can define project-specific tags. Unknown single statement tags are preserved by default; tags that behave like blocks or branches can be configured explicitly.

Input:

Output:

CLI

Published package:

Local plugin build:

API

What The Plugin Handles Today

• HTML elements, void elements, comments, and custom elements • Nunjucks variables: {{ value }}, including whitespace control {{- value -}} • Nunjucks comments: {# comment #} • statement tags such as extends, include, import, from, and custom extension tags • if / elif / elseif / else / endif • for / else / endfor • asyncEach / endeach and asyncAll / endall • block / endblock • macro / endmacro • single-statement set and block set / endset • filter / endfilter • call / endcall • raw / endraw and verbatim / endverbatim preserved verbatim • Nunjucks inside attribute values • Nunjucks blocks that emit attributes • multiline class formatting with conditional modifiers and whitespace-control blocks • embedded JavaScript / CSS formatting for plain script / style tags when the content is safe to parse • raw script / style preservation when content contains Nunjucks or non-JS/CSS types • leading YAML, TOML, and explicit-language front matter preserved without formatting its contents • custom extension block/fork tags via blockTags, inlineTags, and forkTags • incomplete/unmatched template structures preserved as raw nodes instead of crashing

Real-World Examples

Branch chains

Conditional class values

Input:

Output:

Blocks that emit attributes

Raw/verbatim content

Quality Gates

Core check before release:

Package/install checks:

Real-world corpus check:

The OSS corpus currently covers 1,125 real-world Nunjucks templates across 13 public projects, including web.dev, 11ty, Jamstack, A11Y Project, Mozilla Nunjucks, GOV.UK Frontend, and GOV.UK Design System. The check formats each file twice and fails on crashes or non-idempotent output.

Maintainer Release

Run the checks above, then publish from this repository root:

Shared embedding work

See shared embedding architecture and cross-repository dependencies. This source work depends on the core tracking issue.

Description from the npm listing.