Conflict Between Custom Shortcode and Global ImageTransformPlugin

[jonorlin]

Operating system

MacOS Sequoia 15.6.1

Eleventy

6.0.4

Describe the bug

Problem Summary

There appears to be an irreconcilable conflict when using the @11ty/eleventy-img utility inside a custom Nunjucks shortcode alongside the global eleventyImageTransformPlugin. The conflict causes the global plugin's HTML transform to attempt to re-process the shortcode's output, leading to a file path resolution error.

Key Symptoms

The build consistently throws an ENOENT: no such file or directory error, where the file being sought is an output file path generated by the shortcode, but the system is incorrectly looking for that file in the source directory (src).

Error Example:

ENOENT: no such file or directory, stat 'src/assets/img/swiper-out/CjhcAP1RXF-400.jpeg'

• The path it seeks: src/assets/img/swiper-out/... (a source path)
• The file is actually generated at: _site/assets/img/swiper-out/... (an output path)

Reproduction/Isolation Steps

The error persists even after applying standard recommended fixes, confirming a deeper structural conflict:

1. Isolated Setup: The custom shortcode works perfectly when the global transform plugin is removed.
2. Failed Workaround 1 (Filtering): We attempted to use the filter option in the global transform plugin to skip shortcode-generated paths, but the ENOENT error occurred before the filter logic was apparently evaluated.
3. Failed Workaround 2 (Ignoring): We attempted to add the eleventy:ignore attribute to both the generated <picture> tag and the surrounding Nunjucks <div>, but the error persisted, suggesting the file lookup happens too early in the transform chain.

Definitive Solution Used (The Fix)

The only successful solution was to completely remove the global eleventyImageTransformPlugin and manage all image processing via dedicated, asynchronous shortcodes that use explicit Node.js path resolution:

// Example fix used in shortcodes to resolve path ambiguity
const path = require('path'); 
const imagePath = path.join(process.cwd(), 'src', src);

This suggests the issue lies in the internal file path mapping and resolution logic within the html-transformer that is part of the global plugin, which cannot differentiate between an absolute URL intended as a source file and an absolute URL intended as a processed output file.