velocityjs

library2.1.5jsnpmunverified

velocityjs is a JavaScript implementation of the Apache Velocity Template Language (VTL), providing a robust solution for server-side and client-side templating. The current stable version is 2.1.5, offering full compatibility with Java Velocity syntax. It distinguishes itself by separating template parsing into an Abstract Syntax Tree (AST) from the rendering phase, allowing for optimized compilation and execution. Key features include high performance, a lightweight footprint, and comprehensive support for VTL directives such as `#set`, `#foreach`, `#if`, and custom `#macro` definitions. While a specific release cadence isn't detailed, the library appears mature and stable, making it a reliable choice for projects needing VTL capabilities in a JavaScript environment.

serialization web-framework

npm install velocityjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VELOCITYJS

velocityjs

serializationjavascriptv2.1.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

render

✓ import { render } from 'velocityjs'

✗ const { render } = require('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

✓ import { parse } from 'velocityjs'

✗ const parse = require('velocityjs').parse

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

✓ import { Compile } from 'velocityjs'

✗ const Compile = require('velocityjs').Compile

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

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 ``; } } }; 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 <script>alert("XSS!")</script>

Debug

Known issues

gotchaHTML 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 })`.

affects: >=2.0.0

breakingThe 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.

affects: <16.0.0

gotchaWhen 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.

affects: >=2.0.0

gotchaPrior 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.

affects: <2.0.0

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

2.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/shepherdwind/velocity.js ↗

packagehttps://www.npmjs.com/package/velocityjs ↗

homepagehttp://git.shepherdwind.com/velocity.js/ ↗