eleventy-plugin-vento 5.5.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # eleventy-plugin-vento
 
+## 6.0.0
+
+### Major Changes
+
+- ba537b9: Replace `debug` with `obug`
+
+  [Eleventy/Build Awesome is moving from `debug` to `obug` in v4](https://github.com/11ty/buildawesome/issues/4291) and this plugin is getting ahead of the curve. Marked as a major change to guard against any conflicts that might arise from `@11ty/eleventy@<4`. Otherwise, this change should be a drop-in replacement.
+
+## 5.5.1
+
+### Patch Changes
+
+- 3702292: Partially revert 1087bec127bf569a601cb7afb76230b51f5be652, which introduced a regression causing the package to be published without first being built. (fixes #603)
+
 ## 5.5.0
 
 ### Minor Changes
@@ -151,6 +165,7 @@
   More critical to note for Vento v2 is the rearrangement of core library features that this plugin exposes. Definitely review [the changelog for v2](https://github.com/ventojs/vento/blob/main/CHANGELOG.md#200---2025-09-01) to determine whether your implementation needs updating.
 
   The biggest changes are:
+
   - `meriyah` was removed via https://github.com/ventojs/vento/pull/128 at the benefit of performance. If you were absorbing `meriyah`'s functionality via this plugin, you should adjust accordingly.
   - `runStringSync` is no longer supported and has been removed
   - `ventoOptions.useWith` was previously deprecated and has since been removed. If you relied on `useWith` in your [plugin options](https://github.com/noelforte/eleventy-plugin-vento?tab=readme-ov-file#plugin-options), you should instead use `ventoOptions.dataVarname` and `ventoOptions.autoDataVarname` to control how the global namespace for template data is exposed. For more info, see more on [the Vento docs](https://vento.js.org/configuration/#datavarname).
@@ -191,6 +206,7 @@
 ### Minor Changes
 
 - 1f1a13a: Update ventojs to 1.14.0. This version bump incorporates the following new features:
+
   - Loading templates via URLs
   - Destructuring in `for` loops
   - `{{ continue }}` and `{{ break }}` tags
@@ -247,6 +263,7 @@
 - 335f21e: Select type updates (shouldn't affect compilation, however should improve DX)
 
   Changes are:
+
   - split types into separate files
   - namespace `ventojs` type imports
   - make `PluginOptions` optional by default
@@ -254,6 +271,7 @@
   - declare a special (`EleventyVentoEnvironment`) for this plugin to replace Vento's own `Environment`
 
 - 070109a: Refactored files and functions internally that shouldn't have any impact on usage or performance:
+
   - Split `debug` functions into separate exports, renamed `runCompatiblityCheck -> compatibilityCheck` (dd4c379b)
   - Utilities are now split into separate files (e06a83ab)
   - Main file renamed from `index.ts` to `plugin.ts` (1b122d2a)
@@ -284,6 +302,7 @@
 - 335f21e: Select type updates (shouldn't affect compilation, however should improve DX)
 
   Changes are:
+
   - split types into separate files
   - namespace `ventojs` type imports
   - make `PluginOptions` optional by default
@@ -425,6 +444,7 @@
 
 - 7e6ba68: Separate `shortcodes` and `pairedShortcodes` into seperate object namespaces. Prior to this version, Eleventy shortcodes and paired shortcodes were merged into a single object keyed as `_11ty.functions` which allowed for naming collisions between shortcodes and their paired counterparts.
 - b8f0a03: Adds new dependency on `debug` package, to help out with testing and getting more verbose logs. The following `DEBUG` namespaces are implemented:
+
   - `Eleventy:Vento:Setup` - Logs initial setup of the plugin, loading features, pre-page compile setup steps (like changing `page` and `eleventy` objects)
   - `Eleventy:Vento:Cache` - Logs updates to Vento's own internal cache, which is used in tandem with Eleventy's cache.
   - `Eleventy:Vento:Template` - Logs rendered templates and other template related actions
@@ -483,6 +503,7 @@
 ### Patch Changes
 
 - 9f5a90f: Various Refactors - These changes shouldn't have any observable effect on your templates or usage.
+
   - Replaced `class` based approach for a closure implementation instead. Since there was only 1 Vento `env` object ever instanced in this plugin, steering away from using `class` removes some complexity and overhead.
 
   - `DATA_KEYS` (used internally) moved into utils file alongside other utilities (like compatibility checks) and renamed to `CONTEXT_DATA_KEYS`.
@@ -555,7 +576,7 @@
 
   ```js
   eleventyConfig.addPlugin(VentoPlugin, {
-    autotrim: ['@vento', '@11ty', 'tag1', 'tag2'],
+    autotrim: ["@vento", "@11ty", "tag1", "tag2"],
   });
   ```
 

package/dist/plugin.d.mts

@@ -0,0 +1,66 @@
+import * as ventojs$1 from "ventojs";
+import _UserConfig from "@11ty/eleventy/UserConfig";
+import { Plugin } from "ventojs/core/environment.js";
+//#region src/types/utilities.d.ts
+/**
+ * Matches any given string so autocomplete in literal unions works as expected
+ */
+type AnyString = string & Record<never, never>;
+//#endregion
+//#region src/types/eleventy.d.ts
+interface UserConfig extends _UserConfig {
+  directories: {
+    input: string;
+    output: string;
+    includes: string;
+    layouts: string;
+  };
+}
+//#endregion
+//#region src/types/options.d.ts
+interface PluginOptions {
+  /**
+   * An array of Vento plugins
+   */
+  plugins: Plugin[];
+  /**
+   * Enables Vento's autotrim plugin.
+   * @example
+   * // Set to an array of tags
+   * autotrim: ['tag1', 'tag2']
+   * @example
+   * // Use Vento's defaults and Eleventy paired shortcodes
+   * // Setting `true` is functionally equivalent to both
+   * // `@vento` and `@11ty` being present
+   * autotrim: ['@vento', '@11ty']
+   * autotrim: true
+   */
+  autotrim: ('@11ty' | '@vento' | AnyString)[] | boolean;
+  /**
+   * Enable use of Eleventy filters
+   */
+  filters: boolean;
+  /**
+   * Enable use of Eleventy shortcodes
+   */
+  shortcodes: boolean;
+  /**
+   * Enable use of Eleventy paired shortcodes
+   */
+  pairedShortcodes: boolean;
+  /**
+   * A Vento configuration object.
+   * @see {@link https://vento.js.org/configuration/}
+   * @default
+   * {
+   *   // Defaults to Eleventy's own `includes` directory
+   *   includes: eleventyConfig.directories.includes
+   * }
+   */
+  ventoOptions: ventojs$1.Options;
+}
+//#endregion
+//#region src/plugin.d.ts
+declare function VentoPlugin(eleventyConfig: UserConfig, userOptions?: Partial<PluginOptions>): void;
+//#endregion
+export { VentoPlugin };

package/dist/plugin.mjs

@@ -0,0 +1,257 @@
+import path from "node:path";
+import autotrimPlugin, { defaultTags } from "ventojs/plugins/auto_trim.js";
+import ventojs from "ventojs";
+import { VentoError } from "ventojs/core/errors.js";
+import { styleText } from "node:util";
+import { createDebug } from "obug";
+//#region src/utils/create-vento-tag.ts
+function createVentoTag(tagInfo) {
+	let LEVEL = 1;
+	const IS_PAIRED = tagInfo.group === "paired";
+	const tag = (env, token, output, tokens) => {
+		const code = token[1];
+		if (!(code === tagInfo.name || code.startsWith(`${tagInfo.name} `))) return;
+		const { dataVarname } = env.options;
+		const thisArg = `{
+			page: ${dataVarname}.page,
+			eleventy: ${dataVarname}.eleventy
+		}`;
+		const fn = `__env.utils.eleventyFunctions.get('${tagInfo.group}:${tagInfo.name}')`;
+		const args = [code.replace(tagInfo.name, "").trim()];
+		const compiled = [];
+		if (IS_PAIRED) {
+			const nestedVarname = `__content${output.startsWith("__content") ? LEVEL++ : 0}`;
+			args.unshift(env.compileFilters(tokens, nestedVarname, env.options.autoescape));
+			compiled.push("{", `let ${nestedVarname} = "";`, ...env.compileTokens(tokens, nestedVarname, `/${tagInfo.name}`));
+		}
+		args.unshift(thisArg);
+		compiled.push("{", `const __result = await ${fn}.call(${args.filter(Boolean).join(", ")});`, `${output} += ${env.compileFilters(tokens, "__result", env.options.autoescape)}`, "}");
+		if (IS_PAIRED) compiled.push("}");
+		return compiled.join("\n");
+	};
+	return Object.defineProperty(tag, "name", { value: `${tagInfo.name}_${IS_PAIRED ? `EleventyPairedTag` : `EleventyTag`}` });
+}
+//#endregion
+//#region src/utils/logging.ts
+const debug = {
+	main: createDebug("Eleventy:Vento"),
+	get cache() {
+		return this.main.extend("Cache");
+	},
+	get render() {
+		return this.main.extend("Render");
+	},
+	get error() {
+		return this.main.extend("Error");
+	}
+};
+function warn(...messages) {
+	for (const message of messages) console.error(styleText("gray", "[warning]"), styleText("yellow", message));
+}
+//#endregion
+//#region src/utils/errors.ts
+const LINE_TERMINATOR = /(\r\n?|[\n\u{2028}\u{2029}])/u;
+var EleventyVentoError = class extends Error {
+	static async createFromContext(error) {
+		const ctx = await error.getContext();
+		const err = new this("An unknown error occured processing Vento templates", ctx, error);
+		if (ctx.position === void 0 || ctx.file === void 0) warn(`A \`${ctx.type}\` was thrown, but the exact position within the source code cannot be obtained`, "Use DEBUG=\"Eleventy:Vento*\" to view raw `ErrorContext` information");
+		debug.error("Received `ErrorContext` from Vento: %O", ctx);
+		if (ctx.file === void 0) return err;
+		err.message = `${ctx.type} in ${ctx.file}`;
+		if (ctx.position === void 0 || ctx.source === void 0) return err;
+		const sourceLines = codeToLines(ctx.source);
+		const [sourceLine, sourceColumn] = locateInCode(sourceLines, ctx.position);
+		err.message += `:${sourceLine}:${sourceColumn}:\n\n`;
+		const pad = sourceLine.toString().length;
+		const indent = " ".repeat(pad);
+		for (let line = Math.max(sourceLine - 3, 1); line <= sourceLine; line++) err.message += `${String(line).padStart(pad)} │ ${sourceLines[line - 1].trimEnd()}\n`;
+		err.message += `${indent}   ${" ".repeat(sourceColumn - 1)}^`;
+		if (!ctx.code || ctx.line === void 0 || ctx.column === void 0) return err;
+		const codelines = codeToLines(ctx.code);
+		err.message += `\n\n${indent} │ /// compiled Vento function for ${ctx.file} ///\n${indent} │ ${codelines[ctx.line - 1].trimEnd()}\n${indent}   ${" ".repeat(ctx.column - 1)}^`;
+		return err;
+	}
+	constructor(message, context, cause) {
+		super(message, { cause });
+		this.context = context;
+	}
+};
+/**
+* Converts a code string to an array of lines
+*/
+function codeToLines(code) {
+	const doubleLines = code.split(LINE_TERMINATOR);
+	const lines = [];
+	for (let i = 0; i < doubleLines.length; i += 2) lines.push(`${doubleLines[i]}${doubleLines[i + 1] ?? ""}`);
+	return lines;
+}
+/**
+* Identifies the line/column location from a character index
+*/
+function locateInCode(lines, position) {
+	if (position < 0) return [1, 1];
+	let index = 0;
+	for (const [line, content] of lines.entries()) {
+		const { length } = content;
+		if (position < index + length) return [line + 1, position - index + 1];
+		index += length;
+	}
+	throw new Error(`Positon ${position} is out of bounds for the provided source`);
+}
+//#endregion
+//#region src/engine.ts
+function createVentoEngine(options) {
+	const env = ventojs(options);
+	/**
+	* Load plugins into Vento environment
+	*/
+	function loadPlugins(plugins) {
+		for (const plugin of plugins) env.use(plugin);
+	}
+	/**
+	* Load filters into Vento environment
+	*/
+	function loadFilters(filters) {
+		for (const [name, fn] of Object.entries(filters)) env.filters[name] = function(...args) {
+			const { page, eleventy } = this.data;
+			return fn.apply({
+				...this,
+				page,
+				eleventy
+			}, args);
+		};
+	}
+	/**
+	* Load shortcodes (tags) into Vento environment
+	*/
+	function loadShortcodes(group, shortcodes) {
+		if (!(env.utils.eleventyFunctions instanceof Map)) env.utils.eleventyFunctions = /* @__PURE__ */ new Map();
+		for (const [name, fn] of Object.entries(shortcodes)) {
+			env.utils.eleventyFunctions.set(`${group}:${name}`, fn);
+			env.tags.push(createVentoTag({
+				name,
+				group
+			}));
+		}
+	}
+	/**
+	* Clear one or more items from Vento's cache
+	*/
+	function removeCachedItems(items) {
+		for (let item of items) {
+			item = path.normalize(item);
+			debug.cache("Delete cache entry for %s", item);
+			env.cache.delete(item);
+		}
+	}
+	/**
+	* Given a source string and file, compile or get a cached template function,
+	* then produce an Eleventy render function for it and return it.
+	*/
+	async function getRenderFunction(source, file, options) {
+		debug.main("Getting render function for `%s`", file);
+		let template = await env.cache.get(file);
+		if (template?.source === source) debug.cache("Cache HIT for `%s`, using precompiled template", file);
+		else {
+			try {
+				debug.cache("Cache MISS for `%s`, will compile new template function", file);
+				template = env.compile(source, file);
+			} catch (error) {
+				if (error instanceof VentoError) throw await EleventyVentoError.createFromContext(error);
+				throw error;
+			}
+			if (options?.cache !== false) env.cache.set(file, template);
+		}
+		const render = async (data) => {
+			try {
+				debug.render("Rendering %s", file);
+				const { content } = await template(data);
+				return content;
+			} catch (error) {
+				if (error instanceof VentoError) throw await EleventyVentoError.createFromContext(error);
+				throw error;
+			}
+		};
+		return render;
+	}
+	return {
+		loadPlugins,
+		loadFilters,
+		loadShortcodes,
+		removeCachedItems,
+		getRenderFunction
+	};
+}
+//#endregion
+//#region src/plugin.ts
+function VentoPlugin(eleventyConfig, userOptions) {
+	debug.main("Initializing eleventy-plugin-vento");
+	eleventyConfig.versionCheck(">=3.0.0");
+	const options = {
+		autotrim: false,
+		plugins: [],
+		filters: true,
+		shortcodes: true,
+		pairedShortcodes: true,
+		ventoOptions: { includes: eleventyConfig.directories.includes },
+		...userOptions
+	};
+	debug.main("Merged default and user config: %O", options);
+	const filters = eleventyConfig.getFilters();
+	debug.main("Reading filters from Eleventy: %o", filters);
+	const shortcodes = eleventyConfig.getShortcodes();
+	debug.main("Reading shortcodes from Eleventy: %o", shortcodes);
+	const pairedShortcodes = eleventyConfig.getPairedShortcodes();
+	debug.main("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
+	if (options.autotrim) {
+		const tagSet = new Set(options.autotrim === true ? ["@vento", "@11ty"] : options.autotrim);
+		if (tagSet.has("@vento")) {
+			tagSet.delete("@vento");
+			for (const name of defaultTags) tagSet.add(name);
+		}
+		if (tagSet.has("@11ty")) {
+			tagSet.delete("@11ty");
+			for (const name in pairedShortcodes) tagSet.add(name);
+		}
+		debug.main("Enabled autotrim for tags: %o", tagSet);
+		options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
+	}
+	debug.main("Initializing Vento environment");
+	const engine = createVentoEngine(options.ventoOptions);
+	debug.main("Loading plugins: %o", options.plugins);
+	engine.loadPlugins(options.plugins);
+	if (options.filters) {
+		debug.main("Loading filters: %o", filters);
+		engine.loadFilters(filters);
+	}
+	if (options.shortcodes) {
+		debug.main("Loading shortcodes: %o", shortcodes);
+		engine.loadShortcodes("single", shortcodes);
+	}
+	if (options.pairedShortcodes) {
+		debug.main("Loading paired shortcodes: %o", pairedShortcodes);
+		engine.loadShortcodes("paired", pairedShortcodes);
+	}
+	debug.main("Adding Vento cache handler for eleventy.beforeWatch event");
+	eleventyConfig.on("eleventy.beforeWatch", engine.removeCachedItems);
+	debug.main("Registering .vto as a template format");
+	eleventyConfig.addTemplateFormats("vto");
+	debug.main("Registering .vto extension with eleventy");
+	eleventyConfig.addExtension("vto", {
+		outputFileExtension: "html",
+		read: true,
+		async compile(inputContent, inputPath) {
+			inputPath = path.normalize(inputPath);
+			return await engine.getRenderFunction(inputContent, inputPath, { cache: false });
+		},
+		compileOptions: { async permalink(permalinkContent, inputPath) {
+			if (typeof permalinkContent !== "string" || !/\{\{\s+.+\s+\}\}/.test(permalinkContent)) return permalinkContent;
+			inputPath = `EleventyVentoDynamicPermalink:${path.normalize(inputPath)}`;
+			return await engine.getRenderFunction(permalinkContent, inputPath);
+		} }
+	});
+	debug.main("eleventy-plugin-vento initialized");
+}
+//#endregion
+export { VentoPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "5.5.0",
+  "version": "6.0.0",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
@@ -9,8 +9,8 @@
   "types": "./dist/plugin.d.mts",
   "exports": {
     ".": {
-      "import": "./dist/plugin.mjs",
-      "types": "./dist/plugin.d.mts"
+      "types": "./dist/plugin.d.mts",
+      "import": "./dist/plugin.mjs"
     }
   },
   "files": [
@@ -39,24 +39,17 @@
   },
   "license": "MIT",
   "dependencies": {
-    "debug": "4.4.3",
+    "obug": "2.1.4",
     "ventojs": "2.4.0"
   },
   "devDependencies": {
-    "@11ty/eleventy": "3.1.6",
-    "@changesets/cli": "2.31.0",
-    "@eslint/js": "10.0.1",
-    "@types/debug": "4.1.13",
+    "@11ty/eleventy": "4.0.0-alpha.10",
+    "@biomejs/biome": "2.5.7",
+    "@changesets/cli": "2.31.1",
     "@types/node": "24.13.3",
-    "eslint": "10.7.0",
-    "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-unicorn": "71.1.0",
-    "globals": "17.7.0",
-    "knip": "6.26.0",
-    "prettier": "3.9.5",
-    "tsdown": "0.22.4",
+    "knip": "6.31.0",
+    "tsdown": "0.22.14",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.63.0",
     "vitest": "4.1.10"
   }
 }