HTML Tag Generator

Common errors

• TypeError: tag is not a function

  cause Attempting to import `tag` using incorrect ESM syntax (e.g., named import `import { tag } from 'html-tag';`) when the package provides a CommonJS default export.
  fix Use a default import for ESM (`import tag from 'html-tag';`) or the CommonJS `require` syntax (`const tag = require('html-tag');`).

• ReferenceError: require is not defined

  cause Using the CommonJS `require` function within an ECMAScript Module (ESM) file context in Node.js without proper compatibility setup.
  fix Change your import statement to use `import tag from 'html-tag';` if your environment supports ESM. Alternatively, ensure your file is treated as a CommonJS module (e.g., by using a `.cjs` extension or setting `"type": "commonjs"` in `package.json`).

• SyntaxError: Unexpected token '{'

  cause This error can occur if you're trying to destructure a CommonJS default export in an environment that strictly parses `{}` as object destructuring and does not correctly handle CJS-ESM interop for default exports.
  fix Use a direct default import `import tag from 'html-tag';` instead of destructuring `import { tag } from 'html-tag';` for this CommonJS package.

Warnings

• gotcha The `html-tag` package does not automatically escape special characters within the `text` argument. Passing unvalidated user input directly as text content can lead to Cross-Site Scripting (XSS) vulnerabilities.
  Fix: Always sanitize or escape user-provided text content before passing it to `html-tag` to prevent XSS attacks. Consider using a dedicated HTML escaping utility for text nodes.
• gotcha Boolean attributes are handled strictly based on the boolean `true` or `false` values. Using a string like `'false'` will render the attribute with that string value (e.g., `open="false"`), not remove the attribute.
  Fix: Ensure you pass a strict boolean `true` or `false` for attributes that should behave as boolean HTML attributes. For example, `tag('details', {open: false})` will omit the 'open' attribute, while `tag('details', {open: 'false'})` will produce `open="false"`.
• gotcha The package primarily targets CommonJS environments. While modern Node.js may provide CJS-to-ESM interop, using `import tag from 'html-tag'` might behave unexpectedly or fail in some configurations, especially older ones or specific build tools.
  Fix: The most reliable way to use `html-tag` is via the CommonJS `require` syntax: `const tag = require('html-tag');`. If using ESM, ensure your build setup or Node.js version (>=12 with default interop) correctly handles CJS imports.
• gotcha Passing `false` as the last argument to the `tag` function forces the tag to *not* render a closing tag (e.g., `tag('p', 'text', false)` results in `<p>text`). This behavior is intended for XML compatibility and can produce malformed HTML if not used carefully.
  Fix: Avoid using the `false` argument unless you specifically need to generate XML-like output or are certain your HTML will tolerate unclosed tags. For standard HTML, allow the library to auto-close or recognize void elements.

Install

• npm install html-tag npm
• yarn add html-tag yarn
• pnpm add html-tag pnpm

Imports

• tag

  const tag = require('html-tag');

  This package exports a single function as its default CommonJS export. This is the primary and most reliable way to use it in Node.js environments.
• tag (ESM default)
  wrong:

  import { tag } from 'html-tag';

  correct:

  import tag from 'html-tag';

  For modern Node.js environments configured for ESM, a default import might work, relying on Node.js's CJS-to-ESM interop. However, the package itself does not provide explicit ESM exports. Attempting to destructure a named import (e.g., `{ tag }`) will result in `undefined` because 'tag' is not a named export.
• Type Definition

  import type { TagFunction } from 'html-tag';

  This package does not ship with TypeScript definitions. If type safety is required, you would typically rely on community-provided `@types/html-tag` (if available) or declare module types manually. The example assumes a hypothetical type exists.

Quickstart

Demonstrates how to generate various HTML elements, including attributes, text content, void elements, and handling of boolean attributes using the `html-tag` function.

const tag = require('html-tag');

// Generate a simple anchor tag with text and attributes
console.log(tag('a', {href: 'https://example.com', target: '_blank'}, 'Visit Example'));
// Expected: <a href="https://example.com" target="_blank">Visit Example</a>

// Generate an image tag (a void element) with attributes
console.log(tag('img', {src: 'path/to/image.jpg', alt: 'Descriptive alt text'}));
// Expected: <img src="path/to/image.jpg" alt="Descriptive alt text">

// Generate a div with text content
console.log(tag('div', 'Hello, World!'));
// Expected: <div>Hello, World!</div>

// Generate a details tag with a boolean 'open' attribute
console.log(tag('details', {open: true}));
// Expected: <details open></details>

// Force a tag not to render its closing tag (for XML compatibility)
console.log(tag('p', 'Some text for XML...', false));
// Expected: <p>Some text for XML...