eleventy-plugin-vento 5.2.1 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # eleventy-plugin-vento
 
+## 5.4.0
+
+### Minor Changes
+
+- 712a39d: Error logging improvements (thanks @tmcw for the help on this!)
+
+  Re-implements Vento's `stringifyError` function tailored specifically for Eleventy in order to show errors in a nice format that Eleventy expects
+
+  Notably, the one case where this doesn't work is if Vento cannot capture a position from the source code [due to limitations in Node/Bun](https://github.com/noelforte/eleventy-plugin-vento/issues/408#issuecomment-3748576474). In this case, we'll log a warning to the console...
+
+  ```
+  [warning] A `SyntaxError` was thrown, but the exact position within the source code cannot be obtained
+  [warning] Use DEBUG="Eleventy:Vento*" to view raw `ErrorContext` information
+  ```
+
+  ...and log the entire context object to the `DEBUG` namespace `Eleventy:Vento:Error`:
+
+  ```
+  Eleventy:Vento:Error ErrorContext (via Vento) {
+  Eleventy:Vento:Error   type: 'SyntaxError',
+  Eleventy:Vento:Error   message: "Unexpected token '{'",
+  Eleventy:Vento:Error   source: '<div class="image-grid">\n' +
+  Eleventy:Vento:Error     '  {{ for image of collections.{{gallery}} }}\n' +
+  Eleventy:Vento:Error     '    <img src="{{ image }} ">\n' +
+  Eleventy:Vento:Error     '  {{ /for }}\n' +
+  Eleventy:Vento:Error     '</div>\n',
+  Eleventy:Vento:Error   code: '\n' +
+  Eleventy:Vento:Error     '          var {image,collections,gallery} = it;\n' +
+  Eleventy:Vento:Error     '          {\n' +
+  Eleventy:Vento:Error     '__exports.content += "<div class=\\"image-grid\\">\\n  ";\n' +
+  Eleventy:Vento:Error     '__pos=27;\n' +
+  Eleventy:Vento:Error     'for (let image of __env.utils.toIterator(collections.{{gallery}})) {\n' +
+  Eleventy:Vento:Error     '__exports.content += "\\n    <img src=\\"";\n' +
+  Eleventy:Vento:Error     '__pos=84;\n' +
+  Eleventy:Vento:Error     '__exports.content += (image) ?? "";\n' +
+  Eleventy:Vento:Error     '__exports.content += " \\">\\n  ";\n' +
+  Eleventy:Vento:Error     '}\n' +
+  Eleventy:Vento:Error     '__exports.content += "\\n</div>\\n";\n' +
+  Eleventy:Vento:Error     '}\n' +
+  Eleventy:Vento:Error     '        ',
+  Eleventy:Vento:Error   file: '_includes/partials/imageGrid.vto'
+  Eleventy:Vento:Error } +0ms
+  ```
+
+### Patch Changes
+
+- 9f8c8ae: Update ventojs to v2.3.1
+
+## 5.3.0
+
+### Minor Changes
+
+- bf9130c: Update Vento to v2.3.0
+
+  [Upstream release notes](https://github.com/ventojs/vento/blob/main/CHANGELOG.md#230---2025-12-25)
+
 ## 5.2.1
 
 ### Patch Changes

package/dist/plugin.d.mts

@@ -1,44 +1,105 @@
+/// <reference types="node" />
 import * as ventojs from "ventojs";
-import UserConfig from "@11ty/eleventy/UserConfig";
-import { LiteralUnion } from "type-fest";
+import _UserConfig from "@11ty/eleventy/UserConfig";
 import { Plugin } from "ventojs/core/environment.js";
 
+//#region node_modules/.pnpm/11ty.ts@0.0.7_@11ty+eleventy@3.1.2/node_modules/11ty.ts/dist/index.d.ts
+declare global {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+  interface SymbolConstructor {
+    readonly observable: symbol;
+  }
+}
+/**
+Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const pet: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const pet: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+//#endregion
+//#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[];
+  plugins: Plugin[];
   /**
    * Enables Vento's autotrim plugin.
-   * ```js
+   * @example
    * // Set to an array of tags
    * autotrim: ['tag1', 'tag2']
-   *
+   * @example
    * // Use Vento's defaults and Eleventy paired shortcodes
-   * // If set to `true`, uses both
+   * // Setting `true` is functionally equivalent to both
+   * // `@vento` and `@11ty` being present
    * autotrim: ['@vento', '@11ty']
    * autotrim: true
-   * ```
    */
-  autotrim?: LiteralUnion<'@11ty' | '@vento', string>[] | boolean;
-  /** Enable use of Eleventy filters */
-  filters?: boolean;
-  /** Enable use of Eleventy shortcodes */
-  shortcodes?: boolean;
-  /** Enable use of Eleventy paired shortcodes */
-  pairedShortcodes?: boolean;
+  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.
-   *
-   * **Note that `ventoOptions.includes` defaults to
-   * Eleventy's own `dir.includes` location.**
    * @see {@link https://vento.js.org/configuration/}
+   * @default
+   * {
+   *   // Defaults to Eleventy's own `includes` directory
+   *   includes: eleventyConfig.directories.includes
+   * }
    */
-  ventoOptions?: ventojs.Options;
+  ventoOptions: ventojs.Options;
 }
 //#endregion
 //#region src/plugin.d.ts
-declare function VentoPlugin(eleventyConfig: UserConfig, userOptions: PluginOptions): void;
+declare function VentoPlugin(eleventyConfig: UserConfig, userOptions?: Partial<PluginOptions>): void;
 //#endregion
 export { VentoPlugin };

package/dist/plugin.mjs

@@ -1,6 +1,8 @@
 import path from "node:path";
 import autotrimPlugin, { defaultTags } from "ventojs/plugins/auto_trim.js";
 import createVentoEnv from "ventojs";
+import { VentoError } from "ventojs/core/errors.js";
+import { styleText } from "node:util";
 import createDebugger from "debug";
 
 //#region src/utils/create-vento-tag.ts
@@ -32,11 +34,74 @@ function createVentoTag(tagInfo) {
 }
 
 //#endregion
-//#region src/utils/debuggers.ts
-const debugBaseNamespace = "Eleventy:Vento";
-const debugMain = createDebugger(debugBaseNamespace);
-const debugCache = createDebugger(`${debugBaseNamespace}:Cache`);
-const debugRender = createDebugger(`${debugBaseNamespace}:Render`);
+//#region src/utils/logging.ts
+const debug = {
+	main: createDebugger("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\u2028\u2029])/;
+var EleventyVentoError = class extends Error {
+	constructor(message, context, cause) {
+		super(message, { cause });
+		this.context = context;
+	}
+	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 || !ctx.file) 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 += `${`${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 to... */\n${indent} │ ${codelines[ctx.line - 1].trimEnd()}\n${indent}   ${" ".repeat(ctx.column - 1)}^`;
+		return err;
+	}
+};
+/**
+* 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
@@ -81,13 +146,19 @@ function createVentoEngine(options) {
 	}
 	async function getTemplateFunction(source, file, useVentoCache = true) {
 		let template = await env.cache.get(file);
-		if (template?.source === source) debugCache("Cache HIT for `%s`, used precompiled template", file);
-		else {
+		if (template?.source === source) {
+			debug.cache("Cache HIT for `%s`, using precompiled template", file);
+			return template;
+		}
+		try {
+			debug.cache("Cache MISS for `%s`, will compile new template function", file);
 			template = env.compile(source, file);
-			debugCache(`Cache MISS for \`%s\`, compiled new template; %s\n\n${template}`, file, useVentoCache ? "let Vento cache result" : "defer result caching to Eleventy");
 			if (useVentoCache) env.cache.set(file, template);
+			return template;
+		} catch (error) {
+			if (error instanceof VentoError) throw await EleventyVentoError.createFromContext(error);
+			throw error;
 		}
-		return template;
 	}
 	return {
 		cache: env.cache,
@@ -99,15 +170,20 @@ function createVentoEngine(options) {
 	};
 }
 async function renderVentoTemplate(template, data, from) {
-	debugRender("Rendering `%s`", from);
-	const { content } = await template(data);
-	return content;
+	try {
+		debug.render("Rendering `%s`", from);
+		const { content } = await template(data);
+		return content;
+	} catch (error) {
+		if (error instanceof VentoError) throw await EleventyVentoError.createFromContext(error);
+		throw error;
+	}
 }
 
 //#endregion
 //#region src/plugin.ts
 function VentoPlugin(eleventyConfig, userOptions) {
-	debugMain("Initializing eleventy-plugin-vento");
+	debug.main("Initializing eleventy-plugin-vento");
 	eleventyConfig.versionCheck(">=3.0.0");
 	const options = {
 		autotrim: false,
@@ -118,13 +194,13 @@ function VentoPlugin(eleventyConfig, userOptions) {
 		ventoOptions: { includes: eleventyConfig.directories.includes },
 		...userOptions
 	};
-	debugMain("Merged default and user config: %O", options);
+	debug.main("Merged default and user config: %O", options);
 	const filters = eleventyConfig.getFilters();
-	debugMain("Reading filters from Eleventy: %o", filters);
+	debug.main("Reading filters from Eleventy: %o", filters);
 	const shortcodes = eleventyConfig.getShortcodes();
-	debugMain("Reading shortcodes from Eleventy: %o", shortcodes);
+	debug.main("Reading shortcodes from Eleventy: %o", shortcodes);
 	const pairedShortcodes = eleventyConfig.getPairedShortcodes();
-	debugMain("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
+	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")) {
@@ -135,54 +211,54 @@ function VentoPlugin(eleventyConfig, userOptions) {
 			tagSet.delete("@11ty");
 			for (const name in pairedShortcodes) tagSet.add(name);
 		}
-		debugMain("Enabled autotrim for tags: %o", tagSet);
+		debug.main("Enabled autotrim for tags: %o", tagSet);
 		options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
 	}
-	debugMain("Initializing Vento environment");
+	debug.main("Initializing Vento environment");
 	const engine = createVentoEngine(options.ventoOptions);
-	debugMain("Loading plugins: %o", options.plugins);
+	debug.main("Loading plugins: %o", options.plugins);
 	engine.loadPlugins(options.plugins);
 	if (options.filters) {
-		debugMain("Loading filters: %o", filters);
+		debug.main("Loading filters: %o", filters);
 		engine.loadFilters(filters);
 	}
 	if (options.shortcodes) {
-		debugMain("Loading shortcodes: %o", shortcodes);
+		debug.main("Loading shortcodes: %o", shortcodes);
 		engine.loadShortcodes(shortcodes);
 	}
 	if (options.pairedShortcodes) {
-		debugMain("Loading paired shortcodes: %o", pairedShortcodes);
+		debug.main("Loading paired shortcodes: %o", pairedShortcodes);
 		engine.loadPairedShortcodes(pairedShortcodes);
 	}
-	debugMain("Registering Vento cache handler on eleventy.beforeWatch event");
+	debug.main("Registering Vento cache handler on eleventy.beforeWatch event");
 	eleventyConfig.on("eleventy.beforeWatch", async (updatedFiles) => {
 		for (let file of updatedFiles) {
 			file = path.normalize(file);
-			debugCache("Delete cache entry for %s", file);
+			debug.cache("Delete cache entry for %s", file);
 			engine.cache.delete(file);
 		}
 	});
-	debugMain("Registering .vto as a template format");
+	debug.main("Registering .vto as a template format");
 	eleventyConfig.addTemplateFormats("vto");
-	debugMain("Registering .vto extension with eleventy");
+	debug.main("Registering .vto extension with eleventy");
 	eleventyConfig.addExtension("vto", {
 		outputFileExtension: "html",
 		read: true,
 		async compile(inputContent, inputPath) {
 			inputPath = path.normalize(inputPath);
-			debugMain("Getting template function for `%s`", inputPath);
+			debug.main("Getting template function for `%s`", inputPath);
 			const template = await engine.getTemplateFunction(inputContent, inputPath, false);
 			return async (data) => await renderVentoTemplate(template, data, inputPath);
 		},
 		compileOptions: { async permalink(permalinkContent, inputPath) {
 			if (typeof permalinkContent !== "string" || !/\{\{\s+.+\s+\}\}/.test(permalinkContent)) return permalinkContent;
 			inputPath = "EleventyVentoDynamicPermalink:".concat(path.normalize(inputPath));
-			debugMain("Getting template function for `%s`", inputPath);
+			debug.main("Getting template function for `%s`", inputPath);
 			const template = await engine.getTemplateFunction(permalinkContent, inputPath);
 			return async (data) => await renderVentoTemplate(template, data, inputPath);
 		} }
 	});
-	debugMain("eleventy-plugin-vento initialized");
+	debug.main("eleventy-plugin-vento initialized");
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "5.2.1",
+  "version": "5.4.0",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
@@ -37,25 +37,24 @@
   "license": "MIT",
   "dependencies": {
     "debug": "4.4.3",
-    "ventojs": "2.2.0"
+    "ventojs": "2.3.1"
   },
   "devDependencies": {
-    "11ty.ts": "0.0.6",
+    "11ty.ts": "0.0.7",
     "@11ty/eleventy": "3.1.2",
     "@changesets/cli": "2.29.8",
-    "@eslint/js": "9.39.1",
+    "@eslint/js": "10.0.1",
     "@types/debug": "4.1.12",
-    "@types/node": "24.10.1",
-    "eslint": "9.39.1",
+    "@types/node": "24.11.0",
+    "eslint": "10.0.2",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-unicorn": "62.0.0",
-    "globals": "16.5.0",
-    "knip": "5.70.2",
-    "prettier": "3.6.2",
-    "tsdown": "0.16.7",
-    "type-fest": "5.2.0",
+    "eslint-plugin-unicorn": "63.0.0",
+    "globals": "17.4.0",
+    "knip": "5.85.0",
+    "prettier": "3.8.1",
+    "tsdown": "0.20.3",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.48.0",
-    "vitest": "4.0.14"
+    "typescript-eslint": "8.56.1",
+    "vitest": "4.0.18"
   }
 }

package/readme.md

@@ -4,6 +4,7 @@
 [![Github Actions Status](https://img.shields.io/github/actions/workflow/status/noelforte/eleventy-plugin-vento/ci.yml?style=flat-square&logo=github&logoColor=fff&label=Tests&labelColor=333)](https://github.com/noelforte/eleventy-plugin-vento/actions/workflows/ci.yml)
 [![eleventy-plugin-vento on npm](https://img.shields.io/npm/v/eleventy-plugin-vento?style=flat-square&logo=npm&logoColor=fff&labelColor=333)](https://npmjs.com/package/eleventy-plugin-vento)
 [![Changesets on GitHub](https://img.shields.io/badge/🦋_Changesets-333?style=flat-square)](https://github.com/changesets/changesets/)
+[![Uses Prettier](https://img.shields.io/badge/code_style-prettier-cc00aa?style=flat-square&labelColor=333)](https://prettier.io/)
 
 An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://vento.js.org/) templates.
 
@@ -20,9 +21,7 @@ An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://ve
 
 ## Installing
 
-```sh
-npm install eleventy-plugin-vento
-```
+This plugin is available [via the `npm` registry](https://www.npmjs.com/package/eleventy-plugin-vento). You may install it via any compatible package manager (`npm`, `pnpm`, `yarn`, direct download, etc).
 
 [↑ Return to Top](#contents)
 
@@ -46,7 +45,7 @@ export default function (eleventyConfig) {
 
 ## Plugin Options
 
-This plugin ships with default options out of the box, but you can [pass an options object](https://www.11ty.dev/docs/plugins/#plugin-configuration-options) to your `addPlugin` call to configure things further. The below example shows the configurable options as well as their defaults.
+This plugin ships with default options out of the box, but you can [pass an options object](https://www.11ty.dev/docs/create-plugin/#plugin-configuration-options) to your `addPlugin` call to configure things further. The below example shows the configurable options as well as their defaults.
 
 ```js
 import { VentoPlugin } from 'eleventy-plugin-vento';
@@ -232,9 +231,10 @@ Vento: See [Auto Trim Plugin](https://vento.js.org/plugins/auto-trim/).
 
 Like Eleventy, this plugin uses the [`debug`](https://www.npmjs.com/package/debug) package to handle verbose logging. The following `DEBUG` namespaces are implemented:
 
-- `Eleventy:Vento` - Logs initial setup of the plugin, loading features, pre-page compile setup steps (like changing `page` and `eleventy` objects)
+- `Eleventy:Vento` - 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:Render` - Logs when templates are rendered
+- `Eleventy:Vento:Render` - Logs when templates are rendered.
+- `Eleventy:Vento:Error` - Logs extra debugging information when errors occur.
 
 Because it is a child of the `Eleventy:` namespace, the following command will include output from this plugin as well: