Utility Template Tags for ES2015+

1.8.2 · active · verified Tue Apr 21

common-tags provides a collection of reusable template literal tag functions for JavaScript (ES2015+). These tags offer functionalities like HTML escaping (`html`, `safeHtml`), string stripping and indentation (`stripIndent`, `oneLine`), and list formatting (`commaLists`, `inlineLists`). The current stable version is 1.8.2. While there's a pre-release v2.0.0-alpha.1 hinting at future TypeScript adoption and documentation rewrite, the package has a relatively stable, though not very frequent, release cadence for major features, with minor patches addressing bugs or internal tooling. It differentiates itself by offering a robust, well-tested set of common string manipulation utilities often needed when working with template literals, particularly for generating clean, formatted output like HTML or SQL, without the overhead of larger templating engines. It also provides an API for creating custom tags, emphasizing modularity and extensibility for custom text processing scenarios. Since version 1.8.0, it is entirely dependency-free, making it a lightweight choice for modern JavaScript projects.

Common errors

```
TypeError: common_tags_1.html is not a function
```
cause This typically occurs in TypeScript or bundled environments when `common-tags` (an ESM module or CJS with named exports) is imported incorrectly, often due to misconfiguration of `esModuleInterop` or incorrect default import usage.

fix Ensure you are using named imports: `import { html } from 'common-tags';`. For CommonJS, use `const { html } = require('common-tags');`. Verify your TypeScript `tsconfig.json` includes `"esModuleInterop": true` if using mixed module types.
```
ReferenceError: html is not defined
```
cause The `html` tag function (or any other common-tags utility) was used without being correctly imported or destructured from the `common-tags` package.

fix Add the necessary import statement at the top of your file: `import { html } from 'common-tags';` for ES Modules or `const { html } = require('common-tags');` for CommonJS.
```
TypeError: Template tag functions cannot be called directly
```
cause Template tags are special functions designed to be used with template literals (backticks). This error suggests you are attempting to call a tag like a regular function, e.g., `html('<div>Hello</div>')` instead of `html`Hello``.

fix Always use template tag functions by preceding a template literal with the tag's name: `html`<div>Hello</div>`.

Warnings

breaking In `v2.0.0-alpha.1` (a pre-release), the `TemplateTag` class no longer automatically detects if an argument is a function and calls it. This change affects users who create custom tags and relied on this implicit behavior.
Fix: Explicitly call functions passed as arguments within your custom `TemplateTag` implementation if you relied on the previous automatic function detection and execution.
gotcha The maintainer changed their GitHub handle from `declandewet` to `zspecza`. While fixed in `v1.8.1`, older references, documentation, or hardcoded repository links might be outdated or broken, potentially causing confusion or issues with tooling that relies on the old path.
Fix: Ensure all references to the `common-tags` repository, especially in package managers or CI/CD configurations, point to `https://github.com/zspecza/common-tags`.
gotcha In versions prior to `v1.8.0`, the order of calling `valueOf` and `toString` on objects in templates was non-spec compliant. This could lead to unexpected string coercion behavior compared to standard JavaScript template literals.
Fix: Upgrade to `common-tags@1.8.0` or higher to ensure correct `valueOf` and `toString` call order, aligning with JavaScript specification.

Install

npm install common-tags npm
yarn add common-tags yarn
pnpm add common-tags pnpm

Imports

html
wrong:
```
const html = require('common-tags').html;
```
correct:
```
import { html } from 'common-tags';
```
Primary way to import the `html` tag for safely processing HTML in template literals. CommonJS users should use named property access after require.
stripIndent
wrong:
```
import stripIndent from 'common-tags';
```
correct:
```
import { stripIndent } from 'common-tags';
```
Used for removing leading indentation from multiline strings. All core tags are named exports; there is no default export for utility tags.
TemplateTag
wrong:
```
import TemplateTag from 'common-tags/TemplateTag';
```
correct:
```
import { TemplateTag } from 'common-tags';
```
This class is used for creating custom template tags and is a named export from the main package. Direct import from a submodule path is incorrect.

Quickstart

This example demonstrates the use of `html` for basic templating with variable interpolation, `stripIndent` for cleaning up multiline strings, and `oneLine` for condensing strings to a single line, showcasing common use cases for the library's tags.

import { html, stripIndent, oneLine } from 'common-tags';

const user = {
  name: "Jane Doe",
  email: "jane.doe@example.com",
  id: "user-123",
  description: `
    Jane is a passionate software engineer
    with a focus on front-end development.
    She loves open source and contributes
    to several projects.
  `
};

// Using 'html' tag for safe HTML generation and 'stripIndent' for formatting
const userCard = html`
  <div id="${user.id}">
    <h2>${user.name}</h2>
    <p>Email: <a href="mailto:${user.email}">${user.email}</a></p>
    <h3>About:</h3>
    ${stripIndent`${user.description}`}
  </div>
`;

// Using 'oneLine' tag for compact output
const compactInfo = oneLine`
  User: ${user.name}, ID: ${user.id}, 
  Email: ${user.email}
`;

console.log(userCard);
console.log("\n--- Compact Info ---");
console.log(compactInfo);

view raw JSON →