Copyright 2024
';\n } else {\n return ``;\n }\n }\n};\nconst template = '#include(\"header.vm\") Hello $name! Today is $date. #include(\"footer.vm\")';\nconst context = { name: 'Velocity.js User', date: new Date().toLocaleDateString() };\nconst renderedWithMacros = render(template, context, macros);\nconsole.log(renderedWithMacros);\n\n// Using Compile for performance or advanced parsing\nconst asts = parse('The answer is $answer.');\nconst compiledTemplate = new Compile(asts, { escape: true }); // Enable HTML escaping\nconst compiledResult = compiledTemplate.render({ answer: '' });\nconsole.log(compiledResult); // Output: The answer is <script>alert("XSS!")</script>","lang":"typescript","description":"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."},"warnings":[{"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 })`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js installation to version 16.0.0 or newer. Check your `package.json`'s `engines` field for consistency.","message":"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.","severity":"breaking","affected_versions":"<16.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: (0, velocityjs__WEBPACK_IMPORTED_MODULE_0__.render) is not a function"},{"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).","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.","error":"Error: Undefined variable in development environment: $myVariable"},{"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.","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`.","error":"ReferenceError: $user is not defined at line 1, column 5"}],"ecosystem":"npm"}