Nunjucks searchPaths precedence change introduced risk of cyclical includes via path name collisions

[robertdeniszczyc2]

Hi,

The issue

The Nunjucks searchPaths precedence order means there is a risk of cyclical includes which results in render errors when trying to build a project.

Why does it happen?

The issue lies where a consumer of x-govuk/govuk-eleventy-plugin has a directory structure matching the plugin, but where they might be extending layouts.

For example, if I am consuming x-govuk/govuk-eleventy-plugin and in my project I have a file layouts/post.njk which then extends the x-govuk/govuk-eleventy-plugin post.njk like:

{% extends "layouts/post.njk" %}

<!-- my extra content goes here. !-->

When I try to build the project with npx eleventy I will get the error like (redacted exact file paths):

[11ty] Problem writing Eleventy templates:
[11ty] 1. Having trouble writing to "<MY-BUILT-DIRECTORY-PATH>" from "<MY-SOURCE-DIRECTORY-PATH>" (via EleventyTemplateError)
[11ty] 2. (./_includes/layouts/post.njk)
[11ty]   RangeError: Maximum call stack size exceeded (via Template render error)

What I think is happening due to the precedence change, is when the files are being loaded into Nunjucks, the precedence change means that when my post.njk file is loaded and rendered, the extends statement now means that the build tries to extend the template from itself because the search path will match at layouts/post.njk, rather than the search first hitting the plugin version to extend from.

The searchPaths precedence reordering means the x-govuk/govuk-eleventy-plugin/layouts/*.njk files are now like reserved keyword/paths, and consumers of x-govuk/govuk-eleventy-plugin are at risk of path collisions because the file loader will try to load on the first hit, which is now potentially loading itself.

How have I tested this theory?

I've tested this is the cause through the methods:

1. By testing locally reverting the searchPaths change and the project builds OK.
2. Changing my project paths by renaming my layouts to be for example mypost.njk instead of post.njk to ensure there are no path collisions.
3. Explicitly referencing the plugin layouts (like {% extends "../../node_modules/@x-govuk/govuk-eleventy-plugin/layouts/base.njk" %} ) resolves the issue

Where was the issue introduced?

The changes introduced in #354 to resolve #345

Is there an open source project I can see the issue?

Yes, the issue can be observed on this repo: UKHomeOffice/engineering-guidance-and-standards#497

What's the solution?

As per the discussion on our affected repo PR we as consumers of the plugin can get around the issue by using explicit path references where we want to use plugin layouts.

Perhaps this is something the plugin can warn for, or to be added into the docs?

Thankyou!

[jeff-horton-ho-sas]

https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts.md?plain=1#L184-L185

To work with the new precedence this would need to be:

{# Plugin layouts can be loaded from "layouts" #}
{% extends "../../node_modules/@x-govuk/govuk-eleventy-plugin/layouts/page.njk" %}

[chrisns]

Analysis: Cyclical Template Includes (Issue #362)

Thanks for the detailed report and reproduction steps. I've investigated this and can confirm the issue.

Root Cause

Commit 95db584 ("Change precedence of nunjucks searchPaths") reversed the template resolution order to fix #345 (allowing users to override plugin templates):

Before:

searchPaths = [
  './node_modules/@x-govuk/govuk-eleventy-plugin',  // Plugin first
  './node_modules/govuk-frontend/dist',
  resolveNpmModule('@x-govuk/govuk-prototype-components'),
  ...(includes ? [...] : []),  // User directories last
  ...(layouts ? [...] : []),
  input
]

After:

searchPaths = [
  ...(includes ? [...] : []),  // User directories first
  ...(layouts ? [...] : []),
  input,
  './node_modules/@x-govuk/govuk-eleventy-plugin/src',  // Plugin last
  './node_modules/govuk-frontend/dist',
  resolveNpmModule('@x-govuk/govuk-prototype-components/src')
]

This creates a conflict between two valid use cases:

Use Case	Requirement	Current Status
Override plugin template	User dirs searched first	✅ Works
Extend plugin template (same filename)	Plugin template findable	❌ Infinite recursion

When a user creates layouts/post.njk containing {% extends "layouts/post.njk" %}, Nunjucks finds the user's own file first and attempts to extend itself.

Potential Solutions

Option 1: Documentation Only (Minimal Change)

Document that when extending a plugin template with the same filename, users must use the explicit path:

{% extends "node_modules/@x-govuk/govuk-eleventy-plugin/src/layouts/post.njk" %}

Pros: No code changes needed
Cons: Fragile, verbose, poor developer experience

---

Option 2: Namespaced Plugin Templates

Register plugin templates under a distinct namespace prefix (e.g., x-govuk/):

{% extends "x-govuk/layouts/post.njk" %}

This could be achieved by adding a symlink or alias in the searchPaths configuration.

Pros: Clean syntax, unambiguous resolution
Cons: Breaking change for existing extends, requires migration

---

Option 3: Dual Registration

Register plugin templates twice - once under layouts/ (for override behaviour) and once under a prefixed path like plugin-layouts/ or x-govuk-layouts/ (for explicit extension):

{% extends "x-govuk-layouts/post.njk" %}

Pros: Backwards compatible, explicit when needed
Cons: Slight complexity increase

---

Option 4: Custom Nunjucks Tag

Add a custom tag that explicitly resolves to the plugin directory:

{% extends_plugin "layouts/post.njk" %}

Pros: Very explicit intent
Cons: Non-standard Nunjucks, learning curve

---

Option 5: Warning Detection

Add build-time detection when a user template might cause recursion (same name as plugin template + extends that name) and emit a helpful warning.

Pros: Helps users diagnose the issue
Cons: Doesn't fix the underlying problem

---

Recommendation

I'd suggest Option 3 (Dual Registration) as it:

• Maintains backwards compatibility
• Provides a clear escape hatch for the extend-same-name use case
• Doesn't require users to change existing overrides

The implementation would involve adding an additional searchPath entry that maps x-govuk-layouts/ → node_modules/@x-govuk/govuk-eleventy-plugin/src/layouts/.

Offering to Help

I'm happy to submit a PR implementing whichever approach the maintainers prefer. A quick steer on the preferred direction would be helpful:

1. Which solution approach seems most appropriate for this project?
2. Is there a preferred naming convention for the namespace/prefix?
3. Should we also add documentation for the explicit path workaround in the meantime?

Looking forward to your thoughts.