Velocity.js

A JavaScript implementation of the Apache Velocity template engine.

Features

• ✨ Full support for both client-side and server-side rendering
• 🔄 Separation of template parsing and rendering phases
• 🎯 Complete compatibility with Java Velocity syntax
• 🚀 High performance and lightweight

Installation

npm install velocityjs

Quick Start

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

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

// With macros
const macros = {
  include: (path) => `Included content from ${path}`,
};
const template = '#include("header.vm") Hello $name!';
const rendered = render(template, { name: 'World' }, macros);

API Reference

Core Methods

render(vm, context, macros)

Renders a Velocity template string with the provided context and macros.

Parameters:

• vm (string) - Velocity template string
• context (object) - Data context for template variables
• macros (object) - Custom macro functions

Returns: (string) Rendered output

parse(vm, config, ignorespace)

Parses a Velocity template into an AST (Abstract Syntax Tree).

Parameters:

• vm (string) - Velocity template string
• config (object) - Parsing configuration
• ignorespace (boolean) - Whether to ignore whitespace trimming

Returns: (Array) AST nodes

Compile

Compiles parsed AST into a renderable template.

import { parse, Compile } from 'velocityjs';

const asts = parse('Hello $name!');
const template = new Compile(asts);
const result = template.render({ name: 'World' });

Configuration Options

Compile Configuration

• escape (boolean) - Enable HTML escaping for variables (default: false)
• unescape (object) - Specify variables to exclude from escaping
• env (string) - Set to 'development' to throw errors on null values
• valueMapper (function) - Custom value transformation for #set directives
• customMethodHandlers (Array) - Custom function behavior implementations

Context and Macros

Context Object

The context object provides data and methods to your templates:

• Properties are accessed using dot notation: $user.name
• Methods can be called directly: $formatDate($date)
• Methods have access to an eval method for dynamic rendering

Macros

Custom macro functions can be defined for directives like #include:

import { render } from 'velocityjs';

const macros = {
  include: (path) => {
    // Custom include implementation
    return readFile(path);
  },
};

Supported Directives

• #set - Variable assignment
• #foreach - Loop iteration
• #if/#else/#elseif - Conditional logic
• #macro - Template macro definition
• #break - Loop control
• #stop - Template execution control

Getting Help

• 📝 Create an issue
• 📧 Email: eward.song at gmail.com

License

MIT License