HTML Element Shim for Server-Side Templating

2.3.1 · abandoned · verified Tue Apr 21

html-element is a server-side shim providing a partial implementation of `HTMLElement` for Node.js environments. It enables client-side templating libraries, such as Hyperscript, to execute server-side without a full browser DOM. The current stable version is 2.3.1, released in August 2016. The project appears to be in an abandoned state with no significant updates since 2017, making its release cadence non-existent. Its primary differentiation is its lightweight nature, offering just enough DOM API to render templates without the overhead of a headless browser, focusing on core element creation, manipulation, and serialization methods like `createElement`, `appendChild`, `setAttribute`, and `toString()`. It supports Node.js versions 4.2 and higher.

Common errors

```
ReferenceError: document is not defined
```
cause Attempting to access `document` global after upgrading from `html-element` v1 to v2 without adjusting import statements.

fix If you need a global `document` object, change your import to `require('html-element/global-shim');`. Otherwise, import `document` explicitly: `const { document } = require('html-element');`
```
TypeError: Cannot read property 'createElement' of undefined
```
cause The main `html-element` export was `require()`d, but `document` was not accessed as a property, or the wrong import method was used for `document`.

fix Ensure you are accessing `document` correctly: `const { document } = require('html-element');` or `const document = require('html-element').document;`.

Warnings

breaking The package no longer affects the global namespace by default. `require('html-element')` will not create global `document` or `Element` objects.
Fix: If you rely on global objects, change `require('html-element')` to `require('html-element/global-shim')`. For non-global usage, import objects directly: `const { document } = require('html-element');` or `import { Element } from 'html-element';`
breaking Attribute handling was improved in v2.1.0 to distinguish more realistically between IDL (HTML properties like `htmlFor`) and Content attributes (HTML attributes like `for`). HTML output no longer reflects arbitrary properties into attributes.
Fix: Review code that sets properties expecting them to always reflect as HTML attributes. Use `setAttribute()` for explicit HTML attributes.
gotcha Node.js 4.2 LTS or higher is required. Older Node.js versions will not be supported.
Fix: Ensure your Node.js environment is version 4.2 or newer.
gotcha `Node.insertBefore()` now correctly appends a new node if its `referenceNode` argument is `null`, aligning with DOM API specifications.
Fix: No fix needed, but be aware of this behavior change if your code previously relied on `insertBefore(newNode, null)` *not* appending.
gotcha The `textContent` property can now be set on `Element` nodes, which removes all existing children and replaces them with a single text node.
Fix: No fix needed, but be aware that setting `textContent` will overwrite existing child nodes.
gotcha `Element` instances now expose a `tagName` property, which returns the uppercase tag name of the element.
Fix: Update any code that previously tried to infer the tag name from other properties or lacked this capability.

Install

npm install html-element npm
yarn add html-element yarn
pnpm add html-element pnpm

Imports

Element

wrong:

const Element = require('html-element').Element;

correct:

import { Element } from 'html-element';

For non-global usage, import named exports directly since v2.

document
wrong:
```
import { document } from 'html-element';
```
correct:
```
const document = require('html-element').document;
```
The 'document' object is exposed as a property of the main CommonJS export. It is not a named ESM export.

Global Shim

wrong:

require('html-element'); // In v2+, this does NOT create globals.

correct:

require('html-element/global-shim'); // Creates global document, Element, etc.

To restore v1 global behavior, explicitly require the global-shim since v2.0.0.

Quickstart

Demonstrates basic usage of `html-element` to create a document, elements, set attributes and text content, then render to HTML string.

const { document } = require('html-element');

const body = document.createElement('body');
const div = document.createElement('div');
div.setAttribute('id', 'container');
div.setAttribute('class', 'wrapper');
div.textContent = 'Hello, html-element!';

const h1 = document.createElement('h1');
h1.textContent = 'Page Title';

body.appendChild(h1);
body.appendChild(div);

const renderedHtml = body.toString();
console.log(renderedHtml);
/* Expected output:
<body><h1>Page Title</h1><div id="container" class="wrapper">Hello, html-element!</div></body>
*/

view raw JSON →