eleventy-plugin-vento 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # eleventy-plugin-vento
 
+## 3.3.0
+
+### Minor Changes
+
+- 387eb48: ⚠️ DEPRECATION NOTICE: Ignore tag `{{! ... }}` syntax is now deprecated and will be removed in 4.0.0.
+
+  This change comes in favor of using string literals to "pass through" tags without rendering them, like so:
+
+  ```diff
+  - {{! if condition }}
+  + {{ '{{ if condition }}' }}
+      do something
+  - {{! /if }}
+  - {{ '{{ /if }}' }}
+  ```
+
+  While more verbose, this change ensures that there isn't any ambiguity between a tag that needs ignoring and JS negation expressions:
+
+  ```hbs
+  <!-- These are functionally equivalent and can lead to collisions in rendering functionality -->
+
+  {{! conditionStatementToIgnore }}
+
+  {{ !conditionStatementToIgnore }}
+  ```
+
+  If an improved syntax for deferred rendering scenarios ever makes its way to Vento, it will be made available in this plugin.
+
+## 3.2.0
+
+### Minor Changes
+
+- f9388e1: Further refine caching between Eleventy and Vento: commit ec02a765 deferred **all** caching to Vento and turned off Eleventy's cache (released in 3.1.0). This release allows Vento to cache only the templates that Eleventy can't cache (permalinks, includes, etc.), and Eleventy caches everything else.
+
+  A performance oversight has also been resolved by this change. Now, template functions are pre-compiled and saved by Eleventy, only running the template on render without having to go through a re-compile or get a template from the cache.
+
+### Patch Changes
+
+- 693e1a2: Refactored the following features internally:
+
+  - Reverts 2c3548c1 for modularity: The compatibility check has moved back to `modules/utils.js`
+  - Revises caching further: Instead of deferring to Vento for everything, permalink templates and templates loaded by Vento (like includes) are cached by Vento. Everything else is cached by Eleventy.
+  - Rename some internal variables to help with readability (`_11ty.ctx => _11Ctx`)
+  - `DEBUG` key `Eleventy:Vento:Template` renamed to `Eleventy:Vento:Render`
+  - Declare engine functions separately and return as an object after everything has been declared.
+
 ## 3.1.0
 
 ### Minor Changes

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
     "node": ">=16"
   },
-  "imports": {
-    "#11ty-test": "./tests/_utils/eleventy-test.js"
-  },
   "exports": {
     ".": {
       "import": "./src/index.js"
@@ -47,7 +44,7 @@
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-unicorn": "56.0.0",
     "globals": "15.11.0",
-    "vitest": "2.1.3"
+    "vitest": "2.1.4"
   },
   "prettier": {
     "bracketSameLine": true,
@@ -56,7 +53,7 @@
     "trailingComma": "es5"
   },
   "scripts": {
-    "test": "vitest --run",
+    "test": "vitest",
     "lint": "eslint '**/*.js'",
     "ci:version": "changeset version && pnpm install --no-frozen-lockfile",
     "ci:publish": "changeset publish",

package/readme.md

@@ -17,6 +17,7 @@ An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://ve
 [Vento Plugins](#vento-plugins)<br>
 [Auto-Trimming Tags](#auto-trimming-tags)<br>
 [Ignoring Tags](#ignoring-tags)<br>
+[Debugging](#debugging)<br>
 
 ## Installing
 
@@ -28,7 +29,7 @@ npm install eleventy-plugin-vento
 
 This plugin is ESM only and cannot be required from CommonJS.
 
-If you're using CommonJS and loading it asynchronously (ie `await import`), you will need at **minimum** Eleventy v3.0.0-alpha.15 which provides internal methods this plugin uses to get Eleventy stuff from the config API.
+If you're using CommonJS and loading it asynchronously (ie `await import`), you will need at **minimum** Eleventy v3.0.0-alpha.15 which provides internal methods this plugin uses to retrieve Eleventy features from the config API.
 
 In your Eleventy config:
 
@@ -101,7 +102,7 @@ Eleventy: See [Filters](https://www.11ty.dev/docs/filters/)
 > [!NOTE]
 > Remember, Vento can print any return value from a Javascript expression, as well as [run arbitrary JavaScript](https://vento.js.org/syntax/javascript/) in templates through its `{{> ...}}` operator. In these cases, shortcodes may not be needed depending on your usage.
 
-Single and Paired Shortcodes added via Eleventy's `.addShortcode()`, `addAsyncShortcode()`, `addPairedShortcode()` or `.addAsyncPairedShortcode()` will be automatically loaded into Vento.
+Single and Paired Shortcodes added via Eleventy's `.addShortcode()`, `.addAsyncShortcode()`, `.addPairedShortcode()` or `.addAsyncPairedShortcode()` will be automatically loaded into Vento.
 
 When using shortcodes in your templates, write them like any other Vento tag:
 
@@ -135,7 +136,7 @@ For paired shortcodes, the syntax is the same, just add a closing tag. Paired sh
 
 If you'd prefer to set shortcodes yourself (via a plugin or other method) or prevent Eleventy from loading shortcodes into Vento, set `shortcodes: false` and/or `pairedShortcodes: false` in the plugin options.
 
-> [!CAUTION]
+> [!IMPORTANT]
 > While it's straightforward to load filters via a Vento plugin that appends filters to the filters object as `env.filters.[filter_name]()`, creating custom tags in Vento is more involved. It's highly advised to keep these two options enabled unless you know what you're doing.
 
 ### Relevant Documentation
@@ -200,6 +201,9 @@ Vento: See [Auto Trim Plugin](https://vento.js.org/plugins/auto-trim/).
 
 ## Ignoring Tags
 
+> [!WARNING]
+> This feature is now deprecated as of version 3.3.0. I added it primarily for my own use case, however it can cause more issues than it solves (conflict with `!` negation syntax in JS, ambiguity between ignoring a tag and negating an expression in a template). See the 3.3.0 release notes for more information.
+
 Exclusive to this plugin is the ability to skip processing a vento tag entirely and instead preserve the tag in the markup. This could be useful if you're doing some hybrid rendering and would like to defer certain tags from being processed until load time, so they can be rendered on the server.
 
 This feature is enabled through use of the `enableIgnoreTag` plugin option.
@@ -272,7 +276,7 @@ Like Eleventy, this plugin uses the [`debug`](https://www.npmjs.com/package/debu
 
 - `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
+- `Eleventy:Vento:Render` - Logs when templates are rendered
 
 Because it is a child of the `Eleventy:` namespace, the following command will include output from this plugin as well:
 

package/src/engine.js

@@ -3,11 +3,15 @@
  * a simple API for Eleventy to interface with.
  *
  * @typedef {{eleventy?: Record<string, unknown>, page?: Record<string, unknown>}} EleventyContext
- * @typedef {Context & Record<string, unknown>} EleventyData
+ * @typedef {EleventyContext & Record<string, unknown>} EleventyData
  * @typedef {(...args: unknown[]) => unknown} EleventyFunction
+ * @typedef {Record<string, EleventyFunction>} EleventyFunctionSet
  * @typedef {import('ventojs/src/environment.js').Environment} VentoEnvironment
  * @typedef {VentoEnvironment & {
- *   utils: { _11ty: { ctx: Context, tags: Record<string, EleventyFunction> } }
+ *  utils: {
+ * 	_11tyFns: { shortcodes: EleventyFunctionSet, pairedShortcodes: EleventyFunctionSet }
+ * 	_11tyCtx: EleventyContext
+ * }
  * }} EleventyVentoEnvironment
  */
 
@@ -16,80 +20,107 @@ import ventojs from 'ventojs';
 
 // Internal modules
 import { createVentoTag } from './modules/create-vento-tag.js';
-import { DEBUG, CONTEXT_DATA_KEYS } from './modules/utils.js';
+import { CONTEXT_DATA_KEYS, DEBUG } from './modules/utils.js';
 
 /** @param {import('ventojs').Options} options */
 export function createVentoEngine(options) {
 	/** @type {EleventyVentoEnvironment} */
 	const env = ventojs(options);
-	env.utils._11ty = { ctx: {}, shortcodes: {}, pairedShortcodes: {} };
+	env.utils._11tyFns = { shortcodes: {}, pairedShortcodes: {} };
+	env.utils._11tyCtx = {};
 
-	return {
-		cache: env.cache,
+	/** @param {EleventyData} newContext */
+	function setContext(newContext) {
+		if (env.utils._11tyCtx?.page?.inputPath === newContext?.page?.inputPath) {
+			return;
+		}
 
-		/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
-		loadPlugins(plugins) {
-			for (const plugin of plugins) {
-				env.use(plugin);
-			}
-		},
+		for (const K of CONTEXT_DATA_KEYS) {
+			env.utils._11tyCtx[K] = newContext[K];
+		}
 
-		/** @param {PageData} newContext  */
-		loadContext(newContext) {
-			// Loop through allowed keys and load those into the context
-			for (const K of CONTEXT_DATA_KEYS) {
-				env.utils._11ty.ctx[K] = newContext[K];
-			}
-		},
+		DEBUG.setup('Reload context, new context is: %o', env.utils._11tyCtx);
+	}
 
-		/** @param {Record<string, EleventyFunction>} filters */
-		loadFilters(filters) {
-			for (const [name, fn] of Object.entries(filters)) {
-				env.filters[name] = (...args) => fn.apply(env.utils._11ty.ctx, args);
-			}
-		},
+	/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
+	function loadPlugins(plugins) {
+		for (const plugin of plugins) {
+			env.use(plugin);
+		}
+	}
 
-		/** @param {Record<string, EleventyFunction>} shortcodes */
-		loadShortcodes(shortcodes) {
-			for (const [name, fn] of Object.entries(shortcodes)) {
-				env.utils._11ty.shortcodes[name] = fn;
-				env.tags.push(createVentoTag({ name, group: 'shortcodes' }));
-			}
-		},
+	/** @param {Record<string, EleventyFunction>} filters */
+	function loadFilters(filters) {
+		for (const [name, fn] of Object.entries(filters)) {
+			env.filters[name] = fn.bind(env.utils._11tyCtx);
+		}
+	}
 
-		/** @param {Record<string, EleventyFunction>} pairedShortcodes */
-		loadPairedShortcodes(pairedShortcodes) {
-			for (const [name, fn] of Object.entries(pairedShortcodes)) {
-				env.utils._11ty.pairedShortcodes[name] = fn;
-				env.tags.push(createVentoTag({ name, group: 'pairedShortcodes' }));
-			}
-		},
-
-		/** @param {{ source: string, data: PageData, file?: string }} input */
-		async process(input) {
-			// Reload context
-			this.loadContext(input.data);
-			DEBUG.setup('Reloaded Eleventy/Vento context. New value: %o', env.utils._11ty.ctx);
-
-			// Retrieve the template from the cache
-			let template = env.cache.get(input.file);
-
-			if (template?.source === input.source) {
-				DEBUG.cache('Cache HIT for `%s`, used precompiled template', input.file);
-			} else {
-				template = env.compile(input.source, input.file);
-
-				if (input.file) {
-					DEBUG.cache('Cache MISS for `%s`, compiled new template', input.file);
-					env.cache.set(input.file, template);
-				}
+	/** @param {Record<string, EleventyFunction>} shortcodes */
+	function loadShortcodes(shortcodes) {
+		for (const [name, fn] of Object.entries(shortcodes)) {
+			env.utils._11tyFns.shortcodes[name] = fn;
+			env.tags.push(createVentoTag({ name, group: 'shortcodes' }));
+		}
+	}
+
+	/** @param {Record<string, EleventyFunction>} pairedShortcodes */
+	function loadPairedShortcodes(pairedShortcodes) {
+		for (const [name, fn] of Object.entries(pairedShortcodes)) {
+			env.utils._11tyFns.pairedShortcodes[name] = fn;
+			env.tags.push(createVentoTag({ name, group: 'pairedShortcodes' }));
+		}
+	}
+
+	/**
+	 * @param {string} source
+	 * @param {string} file
+	 * @param {boolean} [useVentoCache=true]
+	 */
+	function getTemplateFunction(source, file, useVentoCache = true) {
+		// Attempt to retrieve template function from cache
+		let template = env.cache.get(file);
+
+		if (template?.source === source) {
+			DEBUG.cache('Cache HIT for `%s`, used precompiled template', file);
+		} else {
+			template = env.compile(source, file);
+
+			DEBUG.cache(
+				`Cache MISS for \`%s\`, compiled new template:\nUse Vento cache: %o\n\n${template}`,
+				file,
+				useVentoCache
+			);
+			if (useVentoCache) {
+				env.cache.set(file, template);
 			}
+		}
+
+		return template;
+	}
 
-			// Run the template
-			DEBUG.template(template.code);
-			const { content } = await template(input.data);
+	/**
+	 * @param {import('ventojs/src/environment.js').Template} template
+	 * @param {EleventyData} data
+	 * @param {string} from
+	 */
+	async function render(template, data, from) {
+		// Load new context
+		setContext(data);
 
-			return content;
-		},
+		// Render template
+		DEBUG.render('Rendering `%s`', from);
+		const { content } = await template(data);
+		return content;
+	}
+
+	return {
+		cache: env.cache,
+		loadPlugins,
+		loadFilters,
+		loadShortcodes,
+		loadPairedShortcodes,
+		getTemplateFunction,
+		render,
 	};
 }

package/src/index.js

@@ -29,7 +29,7 @@ import autotrimPlugin, { defaultTags as autotrimDefaultTags } from 'ventojs/plug
 // Local modules
 import { createVentoEngine } from './engine.js';
 import { ignoreTagPlugin } from './modules/ignore-tag.js';
-import { DEBUG, PERMALINK_PREFIX, REQUIRED_API_METHODS } from './modules/utils.js';
+import { DEBUG, runCompatibilityCheck } from './modules/utils.js';
 
 /**
  * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
@@ -37,18 +37,7 @@ import { DEBUG, PERMALINK_PREFIX, REQUIRED_API_METHODS } from './modules/utils.j
  */
 export function VentoPlugin(eleventyConfig, userOptions) {
 	DEBUG.setup('Initializing eleventy-plugin-vento');
-	DEBUG.setup('Run compatibility check');
-	for (const [method, version] of REQUIRED_API_METHODS) {
-		if (!eleventyConfig?.[method]) {
-			console.error(
-				'[eleventy-plugin-vento] Plugin compatibility error:',
-				`\`${method}\``,
-				'not found. Please use Eleventy',
-				version,
-				'or later.'
-			);
-		}
-	}
+	runCompatibilityCheck(eleventyConfig);
 
 	/** @type {VentoPluginOptions} */
 	const options = {
@@ -69,6 +58,14 @@ export function VentoPlugin(eleventyConfig, userOptions) {
 
 	DEBUG.setup('Merged default and user config: %O', options);
 
+	if (options.ignoreTag) {
+		console.error(
+			'[eleventy-plugin-vento] DEPRECATION NOTICE:',
+			'Plugin was called with `ignoreTag` option, which has been deprecated.',
+			'For more information, see: https://github.com/noelforte/eleventy-plugin-vento/blob/main/readme.md#ignoring-tags'
+		);
+	}
+
 	// Get list of filters, shortcodes and paired shortcodes
 	const filters = eleventyConfig.getFilters();
 	DEBUG.setup('Reading filters from Eleventy: %o', filters);
@@ -153,26 +150,36 @@ export function VentoPlugin(eleventyConfig, userOptions) {
 		outputFileExtension: 'html',
 		read: true,
 
-		// Main compile function
-		async compile(source, file) {
-			file = path.normalize(file);
-			return async (data) => await engine.process({ source, data, file });
+		compile(inputContent, inputPath) {
+			// Normalize input path
+			inputPath = path.normalize(inputPath);
+
+			// Retrieve the template function
+			const template = engine.getTemplateFunction(inputContent, inputPath, false);
+
+			// Return a render function
+			return async (data) => await engine.render(template, data, inputPath);
 		},
 
 		compileOptions: {
-			// Defer all caching to Vento
-			cache: false,
 			// Custom permalink compilation
-			permalink(source, file) {
+			permalink(permalinkContent, inputPath) {
 				// Short circuit if input isn't a string and doesn't look like a vento template
-				if (typeof source === 'string' && /\{\{\s+.+\s+\}\}/.test(source)) {
-					file = PERMALINK_PREFIX + path.normalize(file);
-					return async (data) => engine.process({ source, data, file });
+				if (typeof permalinkContent === 'string' && /\{\{\s+.+\s+\}\}/.test(permalinkContent)) {
+					// Normalize input path
+					inputPath = 'Permalink::' + path.normalize(inputPath);
+
+					// Retrieve the template function
+					const template = engine.getTemplateFunction(permalinkContent, inputPath);
+
+					// Return a render function
+					return async (data) => await engine.render(template, data, inputPath);
 				}
 
-				return source;
+				return permalinkContent;
 			},
 		},
 	});
+
 	DEBUG.setup('eleventy-plugin-vento initialized');
 }

package/src/modules/create-vento-tag.js

@@ -12,8 +12,8 @@ export function createVentoTag(options) {
 		if (!code.startsWith(options.name)) return;
 
 		// Declare helper variables for repeated strings in template
-		const fn = `__env.utils._11ty.${options.group}.${options.name}`;
-		const ctx = '__env.utils._11ty.ctx';
+		const fn = `__env.utils._11tyFns.${options.group}.${options.name}`;
+		const ctx = '__env.utils._11tyCtx';
 		const args = [code.replace(options.name, '').trim()];
 
 		const varname = output.startsWith('__shortcode_content')

package/src/modules/utils.js

@@ -4,7 +4,7 @@ const debugBaseNamespace = 'Eleventy:Vento';
 export const DEBUG = {
 	setup: createDebugger(`${debugBaseNamespace}:Setup`),
 	cache: createDebugger(`${debugBaseNamespace}:Cache`),
-	template: createDebugger(`${debugBaseNamespace}:Template`),
+	render: createDebugger(`${debugBaseNamespace}:Render`),
 };
 
 // Project-wide constants
@@ -17,4 +17,18 @@ export const REQUIRED_API_METHODS = [
 
 export const CONTEXT_DATA_KEYS = ['page', 'eleventy'];
 
-export const PERMALINK_PREFIX = 'EleventyVentoPermalink:';
+// Helper functions
+export function runCompatibilityCheck(config) {
+	DEBUG.setup('Run compatibility check');
+	for (const [method, version] of REQUIRED_API_METHODS) {
+		if (!config?.[method]) {
+			console.error(
+				'[eleventy-plugin-vento] Plugin compatibility error:',
+				`\`${method}\``,
+				'not found. Please use Eleventy',
+				version,
+				'or later.'
+			);
+		}
+	}
+}