doT.js Templating Engine

Common errors

• ReferenceError: doT is not defined

  cause Attempting to use `doT.template` directly in an environment where `doT` is not globally available or correctly imported/required.
  fix For CommonJS (v1.x), ensure `const doT = require('dot');` is at the top of your file. For ESM (v2.x), use `import * as doT from 'dot';` or `import { template } from 'dot';` if only needing specific exports.

• TypeError: doT.template is not a function

  cause This typically occurs when `doT` is imported incorrectly, resulting in `doT` being undefined or an object without the `template` property, or attempting to use `require` on an ESM-only build.
  fix Verify your import statement matches your module system (CommonJS `require` for v1.x, ESM `import` for v2.x). Ensure you're accessing `template` from the correct object returned by the import.

• Property 'varname' does not exist on type '{ argName: string[]; }'

  cause Using the deprecated `varname` option for template arguments with doT.js v2.x in a TypeScript environment.
  fix Replace `varname` with `argName` in your template options object to align with the v2.x API. Example: `{ argName: ['foo', 'bar'] }`.

Warnings

• breaking The template option `varname` was renamed to `argName` in v2.0.0-beta.1. Templates created with `varname` in v1.x will not work as expected if this option is used in v2.x.
  Fix: Update any usage of the `varname` option to `argName` when migrating to v2.x.
• breaking Version 2.x of doT.js generates ES6 code by default and ships with official TypeScript typings, shifting towards ESM. While CJS is still supported, users migrating from v1.x (which is primarily CJS-focused) might need to adjust import statements for optimal compatibility.
  Fix: Review import/require statements and update to `import { template } from 'dot';` for ESM environments, or ensure proper CommonJS interop is configured for mixed environments.
• gotcha doT.js v2.0.0-beta.x versions are currently pre-release. They introduce new features and breaking changes, but should not be used in production environments without thorough testing due to potential instability or further API changes.
  Fix: For production systems, continue using the stable 1.x branch. Evaluate v2.x betas for future migration planning and testing only.
• gotcha Version 1.1.3 patched a code injection vulnerability related to prototype pollution (#291). Older versions are susceptible to this security issue.
  Fix: Ensure you are using doT.js version 1.1.3 or higher to mitigate the prototype pollution vulnerability. Upgrade immediately if on an older 1.x version.

Install

• npm install dot npm
• yarn add dot yarn
• pnpm add dot pnpm

Imports

• template
  wrong:

  const doT = require('dot');
  const template = doT.template;

  correct:

  import { template } from 'dot';

  v2.x introduces official ESM exports. For v1.x, `require('dot')` returns the doT object, and `doT.template` is accessed from there.
• process
  wrong:

  const doT = require('dot');
  doT.process(...);

  correct:

  import { process } from 'dot';

  The `process` utility is part of the core doT object. In v2.x, it's a named export, while in v1.x, it's accessed via the default CommonJS import.
• DoTTemplateFunction

  import type { DoTTemplateFunction } from 'dot';

  Available since v2.x, which ships with official TypeScript declaration files. Provides type safety for compiled template functions.

Quickstart

Demonstrates basic template compilation and rendering using the `template` function, including both `it` context and multi-argument destructuring, as well as a more complex example with control flow.

import { template } from 'dot';

// Basic usage with 'it' context
const basicTmpl = template('Hello, {{=it.name}}!');
console.log(basicTmpl({ name: 'World' }));

// Usage with explicit argName (v2.x feature, fallback for v1.x)
const multiArgTmpl = template(
  'User ID: {{=id}}, Username: {{=username}}',
  { argName: ['id', 'username'] } // This option is 'varname' in v1.x
);
console.log(multiArgTmpl({ id: 123, username: 'jsuser' }));

// A more complex example with conditionals and loops
const listTmpl = template(`
  <h2>{{=it.title}}</h2>
  <ul>
    {{~it.items :item:idx}}
      <li>{{=idx + 1}}. {{=item}}</li>
    {{~}}
  </ul>
  {{? it.footer}}
    <p>{{=it.footer}}</p>
  {{?}}
`);

const data = {
  title: 'My Shopping List',
  items: ['Apples', 'Milk', 'Bread'],
  footer: 'Happy shopping!'
};
console.log(listTmpl(data));