art-template

4.13.4 · active · verified Sun Apr 19

art-template is a high-performance JavaScript template engine designed for both Node.js and browser environments. It achieves near-JavaScript-limit rendering speeds through a 'scope pre-declared' optimization technique. The current stable version is 4.13.4, with a release cadence that addresses bugs, performance, and adds minor features, as seen in recent patch and minor releases (e.g., v4.13.0 for performance fixes, v4.13.2 for type definitions). Key differentiators include its extreme speed, debugging friendliness (accurate error positioning, breakpoint support with Webpack loader), support for template inheritance, sub-templates, and a small browser footprint (6KB). It integrates with popular frameworks like Express and Koa, and build tools like Webpack.

Common errors

```
ReferenceError: window is not defined
```
cause A bug in `art-template` versions prior to `4.13.1` caused it to reference the global `window` object in non-browser environments, such as server-side rendering setups.

fix Upgrade to `art-template@4.13.1` or higher to resolve the issue.
```
Template compilation error: Helper 'someHelper' not found
```
cause Using the v3 `{{helper args}}` syntax for calling helper methods in `art-template` v4, which is no longer supported and throws a compilation error.

fix Refactor template helper calls to use standard JavaScript expression syntax, e.g., `{{ helper.someHelper(args) }}` or `{{ someGlobalFunction(args) }}`.
```
error TS2614: Module '"art-template"' has no exported member 'template'
```
cause Missing or incorrect TypeScript definition files (`index.d.ts`) were not shipped with `art-template` versions up to `4.13.1`, leading to TypeScript compilation errors.

fix Upgrade `art-template` to version `4.13.2` or newer to ensure correct type definitions are included in your project.

Warnings

breaking The `{{helper args}}` syntax for calling helper methods from art-template v3 is no longer compatible. Migrate to the standard JavaScript expression syntax for helpers.
Fix: Update template files to use standard JavaScript expressions for helper calls, as the v3 `{{helper args}}` syntax is deprecated. For example, change `{{helper args}}` to `{{ helper.func(args) }}`.
gotcha The `bail` option, which controls whether template compilation errors immediately throw an exception, now defaults to `true`. This means template errors will halt execution by default.
Fix: If you relied on template errors being suppressed or handled differently, explicitly set `template.defaults.bail = false;` to revert to previous behavior or implement custom error handling.
gotcha TypeScript definition file (`index.d.ts`) was missing in versions up to `4.13.1`, leading to compilation errors or lack of type intelligence for TypeScript users.
Fix: Ensure you are using `art-template` version `4.13.2` or higher to have the correct TypeScript definition files included in the package.
gotcha In some runtime environments, particularly those with a global `window` object but not fully compliant browser APIs (like certain server-side rendering setups), versions prior to 4.13.1 could throw 'window is not defined' errors.
Fix: Upgrade to `art-template` version `4.13.1` or newer to resolve issues related to `window` being undefined in specific runtime contexts.

Install

npm install art-template npm
yarn add art-template yarn
pnpm add art-template pnpm

Imports

template
wrong:
```
import { template } from 'art-template';
```
correct:
```
import template from 'art-template';
```
The primary art-template rendering function or object is exported as the default for both CJS and ESM environments. TypeScript users should prefer the ESM import.
template.defaults
wrong:
```
import { defaults } from 'art-template';
```
correct:
```
import template from 'art-template'; template.defaults.escape = false;
```
Configuration options are managed via the `defaults` property on the main `template` object, not as a separate named export.
template.compile
wrong:
```
import { compile } from 'art-template';
```
correct:
```
import template from 'art-template'; const render = template.compile(source);
```
The `compile` method for pre-compiling templates is a property of the main `template` object/function, not a direct named export.

Quickstart

This quickstart demonstrates how to set up `art-template` with global defaults, register custom filters, compile a template string, and render it with provided data. It showcases basic templating features like variable output, looping, conditionals, and raw HTML output.

import template from 'art-template';

// 1. Configure global defaults (optional)
template.defaults.escape = false; // Disable HTML escaping for raw output

// 2. Define a template string
const templateString = `
  <!DOCTYPE html>
  <html lang="en">
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <h1>Hello, {{ name | capitalize }}!</h1>
    <p>Your items:</p>
    <ul>
      {{ each items }}
        <li>Item #{{ $index + 1 }}: {{ $value }}</li>
      {{ /each }}
    </ul>
    {{ if showFooter }}
      <footer>Rendered at: {{ date | dateFormat }}</footer>
    {{ /if }}
    <p>Raw HTML (if escape is disabled): {{ @rawHtml }}</p>
  </body>
  </html>
`;

// 3. Register a custom filter (optional)
template.defaults.imports.capitalize = (value: string) => {
  return value.charAt(0).toUpperCase() + value.slice(1);
};
template.defaults.imports.dateFormat = (date: Date) => {
  return date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
};


// 4. Compile the template (recommended for performance in production)
const render = template.compile(templateString);

// 5. Define data
const data = {
  title: 'Art Template Example',
  name: 'world',
  items: ['apple', 'banana', 'orange'],
  showFooter: true,
  date: new Date(),
  rawHtml: '<strong>This is bold!</strong>'
};

// 6. Render the template with data
const output = render(data);
console.log(output);

// You can also render directly without pre-compiling for simple cases (less efficient)
const directOutput = template(templateString, {
    title: 'Direct Render Example',
    name: 'test',
    items: ['one', 'two'],
    showFooter: false,
    date: new Date(),
    rawHtml: '<i>Italic!</i>'
});
// console.log(directOutput);

view raw JSON →