{"id":15097,"library":"common-tags","title":"Utility Template Tags for ES2015+","description":"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.","status":"active","version":"1.8.2","language":"javascript","source_language":"en","source_url":"https://github.com/zspecza/common-tags","tags":["javascript","array","babel","es2015","es2015-tag","es6","es6-tag","heredoc","html"],"install":[{"cmd":"npm install common-tags","lang":"bash","label":"npm"},{"cmd":"yarn add common-tags","lang":"bash","label":"yarn"},{"cmd":"pnpm add common-tags","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary way to import the `html` tag for safely processing HTML in template literals. CommonJS users should use named property access after require.","wrong":"const html = require('common-tags').html;","symbol":"html","correct":"import { html } from 'common-tags';"},{"note":"Used for removing leading indentation from multiline strings. All core tags are named exports; there is no default export for utility tags.","wrong":"import stripIndent from 'common-tags';","symbol":"stripIndent","correct":"import { stripIndent } from 'common-tags';"},{"note":"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.","wrong":"import TemplateTag from 'common-tags/TemplateTag';","symbol":"TemplateTag","correct":"import { TemplateTag } from 'common-tags';"}],"quickstart":{"code":"import { html, stripIndent, oneLine } from 'common-tags';\n\nconst user = {\n  name: \"Jane Doe\",\n  email: \"jane.doe@example.com\",\n  id: \"user-123\",\n  description: `\n    Jane is a passionate software engineer\n    with a focus on front-end development.\n    She loves open source and contributes\n    to several projects.\n  `\n};\n\n// Using 'html' tag for safe HTML generation and 'stripIndent' for formatting\nconst userCard = html`\n  <div id=\"${user.id}\">\n    <h2>${user.name}</h2>\n    <p>Email: <a href=\"mailto:${user.email}\">${user.email}</a></p>\n    <h3>About:</h3>\n    ${stripIndent`${user.description}`}\n  </div>\n`;\n\n// Using 'oneLine' tag for compact output\nconst compactInfo = oneLine`\n  User: ${user.name}, ID: ${user.id}, \n  Email: ${user.email}\n`;\n\nconsole.log(userCard);\nconsole.log(\"\\n--- Compact Info ---\");\nconsole.log(compactInfo);","lang":"javascript","description":"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."},"warnings":[{"fix":"Explicitly call functions passed as arguments within your custom `TemplateTag` implementation if you relied on the previous automatic function detection and execution.","message":"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.","severity":"breaking","affected_versions":">=2.0.0-alpha.1"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<1.8.1"},{"fix":"Upgrade to `common-tags@1.8.0` or higher to ensure correct `valueOf` and `toString` call order, aligning with JavaScript specification.","message":"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.","severity":"gotcha","affected_versions":"<1.8.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: common_tags_1.html is not a function"},{"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.","cause":"The `html` tag function (or any other common-tags utility) was used without being correctly imported or destructured from the `common-tags` package.","error":"ReferenceError: html is not defined"},{"fix":"Always use template tag functions by preceding a template literal with the tag's name: `html`<div>Hello</div>`.","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``.","error":"TypeError: Template tag functions cannot be called directly"}],"ecosystem":"npm"}