Velocity.js Template Engine

Common errors

• TypeError: (0, velocityjs__WEBPACK_IMPORTED_MODULE_0__.render) is not a function

  cause This usually indicates an incorrect import statement, especially in environments that transpile ESM to CJS or when using older Node.js versions or bundler configurations not fully supporting ESM named exports.
  fix Ensure you are using `import { render } from 'velocityjs'`. If you are in a strict CommonJS environment, try `const { render } = require('velocityjs')` as a fallback, though direct ESM named imports are preferred for this library.

• Error: Undefined variable in development environment: $myVariable

  cause The `env: 'development'` option was set during compilation, and a variable (`$myVariable`) referenced in the template was not found in the provided context object.
  fix Either ensure the `$myVariable` is always present in your context object, or change the `Compile` configuration to remove `env: 'development'` if you prefer missing variables to resolve silently (e.g., to null).

• ReferenceError: $user is not defined at line 1, column 5

  cause A variable or property, such as `$user.name`, is being accessed in the template, but the base object (`$user`) is not defined or provided in the rendering context, leading to a `ReferenceError`.
  fix Ensure that all top-level variables and objects expected by your template are present in the context object passed to `render` or `Compile.render()`. Use `#if($user) $user.name #end` for optional properties.

Warnings

• gotcha HTML escaping for variables is disabled by default. When rendering user-generated content, you must explicitly enable escaping using `escape: true` in the Compile configuration, or manually sanitize output, to prevent Cross-Site Scripting (XSS) vulnerabilities.
  Fix: Initialize `Compile` with `{ escape: true }` or pass `{ escape: true }` as a config object to `render` if using its internal compilation, e.g., `render(vm, context, macros, { escape: true })`.
• breaking The package requires Node.js version 16.0.0 or higher. Running `velocityjs` in older Node.js environments will result in compatibility errors or failures.
  Fix: Upgrade your Node.js installation to version 16.0.0 or newer. Check your `package.json`'s `engines` field for consistency.
• gotcha When the `Compile` configuration `env` is set to 'development', accessing undefined variables within a template will throw an error instead of silently resolving to `null` or an empty string. While useful for debugging, this can cause unexpected crashes in environments where this behavior is not anticipated.
  Fix: Ensure all variables referenced in templates are always present in the context object. For production, consider omitting `env: 'development'` or implementing robust error handling around template rendering.
• gotcha Prior to version 2, `velocityjs` might have primarily supported CommonJS modules. If migrating from an older version or using a build system that defaults to CommonJS, ensure you are using the correct import syntax (named imports via `import { ... } from 'velocityjs'`) as shown in the documentation.
  Fix: For new projects or updated build setups, use `import { render, parse, Compile } from 'velocityjs'`. If stuck on CommonJS, ensure your bundler (like Webpack or Rollup) correctly handles ESM modules or use `const { render } = require('velocityjs')` if supported by your version and environment.

Install

• npm install velocityjs npm
• yarn add velocityjs yarn
• pnpm add velocityjs pnpm

Imports

• render
  wrong:

  const { render } = require('velocityjs')

  correct:

  import { render } from 'velocityjs'

  ESM import is the standard for modern Node.js and browser environments. CommonJS `require` should be used for older Node.js or specific build configurations.
• parse
  wrong:

  const parse = require('velocityjs').parse

  correct:

  import { parse } from 'velocityjs'

  The `parse` function is used to convert a Velocity template string into an Abstract Syntax Tree (AST) for more advanced processing or pre-compilation.
• Compile
  wrong:

  const Compile = require('velocityjs').Compile

  correct:

  import { Compile } from 'velocityjs'

  Compile is a class used to instantiate a reusable template renderer from a parsed AST. Instantiate with `new Compile(asts)`.

Quickstart

This quickstart demonstrates basic template rendering, the use of custom macros for directives like `#include`, and how to use the `parse` and `Compile` methods for pre-compilation and advanced configuration like HTML escaping.

import { render, parse, Compile } from 'velocityjs';

// Simple rendering
const result = render('Hello $name!', { name: 'World' });
console.log(result); // Output: Hello World!

// With macros and custom logic
const macros = {
  include: (path) => {
    // In a real application, you'd load content from 'path'
    // For this example, we'll simulate it.
    if (path === 'header.vm') {
      return '<h1>Welcome!</h1>';
    } else if (path === 'footer.vm') {
      return '<p>Copyright 2024</p>';
    } else {
      return `<!-- Error: ${path} not found -->`;
    }
  }
};
const template = '#include("header.vm") Hello $name! Today is $date. #include("footer.vm")';
const context = { name: 'Velocity.js User', date: new Date().toLocaleDateString() };
const renderedWithMacros = render(template, context, macros);
console.log(renderedWithMacros);

// Using Compile for performance or advanced parsing
const asts = parse('The answer is $answer.');
const compiledTemplate = new Compile(asts, { escape: true }); // Enable HTML escaping
const compiledResult = compiledTemplate.render({ answer: '<script>alert("XSS!")</script>' });
console.log(compiledResult); // Output: The answer is &lt;script&gt;alert(&quot;XSS!&quot;)&lt;/script&gt;