HTML JSON Converter

A TypeScript library to convert HTML to JSON and vice versa. Supports both Node.js and browser environments.

• HTML JSON Converter
  • Installation
  • Usage
    • Server-Side Usage
    • Browser Usage
  • Features
    • Void Elements
    • Raw Text Elements
    • Nested Elements
    • Supported HTML Elements
    • Document Fragment vs Full Documents
    • Custom Elements
  • Configuration
  • Important Notes
  • License
  • Additional Considerations
  • Examples
    • Handling Malformed HTML
    • Enforcing Rules During Conversion
    • Using in Next.js (Client-Side)
    • For Using in server side in Next.js
  • Feedback and Contributions

Installation

npm install html-json-converter

Usage

Server-Side Usage

import { ServerHTMLJSONConverter } from 'html-json-converter';
// OR use the below import if you want to be specific (Recommended)
import { ServerHTMLJSONConverter } from 'html-json-converter/server';

const converter = new ServerHTMLJSONConverter();

// HTML to JSON
const html = '<div class="test">Hello World</div>';
const json = converter.toJSON(html);
console.log(json);
/* Output:
{
  tag: "div",
  attributes: { class: "test" },
  children: ["Hello World"]
}
*/

// JSON to HTML
const jsonObj = {
  tag: "div",
  attributes: { class: "test" },
  children: ["Hello World"]
};
const htmlOutput = converter.toHTML(jsonObj);
console.log(htmlOutput);
/* Output:
<div class="test">
    Hello World
</div>
*/

Browser Usage

// This is the only way to import the client-side version of the library.
import { ClientHTMLJSONConverter } from 'html-json-converter/client';

const converter = new ClientHTMLJSONConverter();

// Usage is the same as server-side

Features

Void Elements

Void elements are self-closing elements that cannot have children, such as <img>, <br>, <hr>, etc. The converter enforces the rule that void elements cannot have children.

// Valid void element
const html = '<img src="test.jpg" alt="Test"/>';
const json = converter.toJSON(html);
/* Output:
{
  tag: "img",
  attributes: {
    src: "test.jpg",
    alt: "Test"
  }
}
*/

// Attempting to convert a void element with children in JSON to HTML will throw an error
const invalidJson = {
  tag: "img",
  attributes: { src: "test.jpg" },
  children: ["Invalid content"] // This is not allowed
};

try {
  converter.toHTML(invalidJson);
} catch (error) {
  console.error(error.message);
  // Output: Void element <img> cannot have children.
}

Raw Text Elements

Raw text elements, such as <script> and <style>, preserve their content as a single text node.

const html = '<style>.test { color: red; }</style>';
const json = converter.toJSON(html);
/* Output:
{
  tag: "style",
  children: [".test { color: red; }"]
}
*/

Nested Elements

The converter handles nested HTML structures seamlessly.

const html = `
<div class="container">
  <h1>Title</h1>
  <p>Paragraph</p>
</div>
`;
const json = converter.toJSON(html);
/* Output:
{
  tag: "div",
  attributes: { class: "container" },
  children: [
    {
      tag: "h1",
      children: ["Title"]
    },
    {
      tag: "p",
      children: ["Paragraph"]
    }
  ]
}
*/

Supported HTML Elements

| Element | Type | Allows Children | Allows Attributes | |------------------|--------------|---------------------|-----------------------| | a | Normal | Yes | Yes | | abbr | Normal | Yes | Yes | | address | Normal | Yes | Yes | | article | Normal | Yes | Yes | | aside | Normal | Yes | Yes | | audio | Normal | Yes | Yes | | b | Normal | Yes | Yes | | bdi | Normal | Yes | Yes | | bdo | Normal | Yes | Yes | | blockquote | Normal | Yes | Yes | | body | Normal | Yes | Yes | | button | Normal | Yes | Yes | | canvas | Normal | Yes | Yes | | caption | Normal | Yes | Yes | | cite | Normal | Yes | Yes | | code | Normal | Yes | Yes | | colgroup | Normal | Yes | Yes | | data | Normal | Yes | Yes | | datalist | Normal | Yes | Yes | | dd | Normal | Yes | Yes | | del | Normal | Yes | Yes | | details | Normal | Yes | Yes | | dfn | Normal | Yes | Yes | | dialog | Normal | Yes | Yes | | div | Normal | Yes | Yes | | dl | Normal | Yes | Yes | | dt | Normal | Yes | Yes | | em | Normal | Yes | Yes | | fieldset | Normal | Yes | Yes | | figcaption | Normal | Yes | Yes | | figure | Normal | Yes | Yes | | footer | Normal | Yes | Yes | | form | Normal | Yes | Yes | | h1 | Normal | Yes | Yes | | h2 | Normal | Yes | Yes | | h3 | Normal | Yes | Yes | | h4 | Normal | Yes | Yes | | h5 | Normal | Yes | Yes | | h6 | Normal | Yes | Yes | | head | Normal | Yes | Yes | | header | Normal | Yes | Yes | | hgroup | Normal | Yes | Yes | | html | Normal | Yes | Yes | | i | Normal | Yes | Yes | | iframe | Normal | Yes | Yes | | ins | Normal | Yes | Yes | | kbd | Normal | Yes | Yes | | label | Normal | Yes | Yes | | legend | Normal | Yes | Yes | | li | Normal | Yes | Yes | | main | Normal | Yes | Yes | | map | Normal | Yes | Yes | | mark | Normal | Yes | Yes | | menu | Normal | Yes | Yes | | meter | Normal | Yes | Yes | | nav | Normal | Yes | Yes | | noscript | Normal | Yes | Yes | | object | Normal | Yes | Yes | | ol | Normal | Yes | Yes | | optgroup | Normal | Yes | Yes | | option | Normal | Yes | Yes | | output | Normal | Yes | Yes | | p | Normal | Yes | Yes | | picture | Normal | Yes | Yes | | pre | Normal | Yes | Yes | | progress | Normal | Yes | Yes | | q | Normal | Yes | Yes | | rp | Normal | Yes | Yes | | rt | Normal | Yes | Yes | | ruby | Normal | Yes | Yes | | s | Normal | Yes | Yes | | samp | Normal | Yes | Yes | | section | Normal | Yes | Yes | | select | Normal | Yes | Yes | | small | Normal | Yes | Yes | | span | Normal | Yes | Yes | | strong | Normal | Yes | Yes | | sub | Normal | Yes | Yes | | summary | Normal | Yes | Yes | | sup | Normal | Yes | Yes | | table | Normal | Yes | Yes | | tbody | Normal | Yes | Yes | | td | Normal | Yes | Yes | | template | Normal | Yes | Yes | | tfoot | Normal | Yes | Yes | | th | Normal | Yes | Yes | | thead | Normal | Yes | Yes | | time | Normal | Yes | Yes | | tr | Normal | Yes | Yes | | u | Normal | Yes | Yes | | ul | Normal | Yes | Yes | | var | Normal | Yes | Yes | | video | Normal | Yes | Yes | | Void Elements | | | | | area | Void | No | Yes | | base | Void | No | Yes | | br | Void | No | Yes | | col | Void | No | Yes | | embed | Void | No | Yes | | hr | Void | No | Yes | | img | Void | No | Yes | | input | Void | No | Yes | | keygen | Void | No | Yes | | link | Void | No | Yes | | meta | Void | No | Yes | | param | Void | No | Yes | | source | Void | No | Yes | | track | Void | No | Yes | | wbr | Void | No | Yes | | Raw Text Elements | | | | | script | Raw Text | Yes | Yes | | style | Raw Text | Yes | Yes | | textarea | Raw Text | Yes | Yes | | title | Raw Text | Yes | Yes | | Foreign Elements | | | | | svg | Foreign | Yes | Yes | | math | Foreign | Yes | Yes |

Document Fragment vs Full Documents

The converter supports both HTML fragments and full HTML documents.

// Fragment
const fragment = '<p>Hello</p>';
const fragmentJson = converter.toJSON(fragment);
/* Output:
{
  tag: "p",
  children: ["Hello"]
}
*/

// Full Document
const doc = '<!DOCTYPE html><html><body><p>Hello</p></body></html>';
const docJson = converter.toJSON(doc);
/* Output:
{
  tag: "html",
  children: [
    {
      tag: "head"
    },
    {
      tag: "body",
      children: [
        {
          tag: "p",
          children: ["Hello"]
        }
      ]
    }
  ]
}
*/

Custom Elements

You can register custom elements with specific behaviors.

import { ServerHTMLJSONConverter, HTMLElementType } from 'html-json-converter';
const customElements = {
  'my-component': { type: HTMLElementType.NORMAL, allowChildren: true, allowAttributes: true },
  'my-void-element': { type: HTMLElementType.VOID, allowChildren: false, allowAttributes: true }
};

const converter = new ServerHTMLJSONConverter({ customElements });

const html = '<my-component><span>Content</span></my-component>';
const json = converter.toJSON(html);
/* Output:
{
  tag: "my-component",
  children: [
    {
      tag: "span",
      children: ["Content"]
    }
  ]
}
*/

Configuration

You can customize the converter's behavior using the ConverterConfig interface.

import { type ConverterConfig, HTMLElementType,ServerHTMLJSONConverter } from 'html-json-converter';

const config : ConverterConfig = {
  useTab: false,      // Use spaces instead of tabs for indentation
  tabSize: 2,         // Number of spaces per indentation level
  customElements: {   // Register custom elements
    'custom-tag': { type: HTMLElementType.NORMAL, allowChildren: true, allowAttributes: true }
  }
};

const converter = new ServerHTMLJSONConverter(config);

Important Notes

• Enforcement of HTML Rules: The converter enforces certain HTML rules:
  • Void Elements:
    • Cannot have children.
    • Must be self-closing in the output HTML.
  • Non-Void Elements:
    • Cannot be self-closed.
    • Must have separate opening and closing tags, even if they have no children.
• Parser Behavior:
  • When converting HTML to JSON, the converter relies on the HTML parser (JSDOM on the server, DOMParser in the browser).
  • The parser may correct malformed HTML automatically.
  • Invalid HTML (e.g., void elements with children) may be parsed differently than expected due to parser correction.
• Whitespace Handling:
  • Whitespace and indentation in the output HTML are controlled by the useTab and tabSize configuration options.
• Error Handling:
  • The converter will throw errors when attempting to violate enforced HTML rules during conversion.
  • Examples include adding children to void elements in JSON when converting to HTML.

License

This project is licensed under the MIT License.

Additional Considerations

• Graceful Handling of Invalid HTML:
  • While the converter enforces rules during JSON to HTML conversion, it handles invalid HTML input gracefully when converting HTML to JSON.
  • The parser may automatically correct or ignore invalid structures.
• Custom Element Types:
  • You can define custom element types and specify whether they are void, raw text, or normal elements.
  • This allows for flexibility when working with web components or custom tags.
• Cross-Environment Consistency:
  • Both ServerHTMLJSONConverter and ClientHTMLJSONConverter aim to provide consistent behavior across Node.js and browser environments.
  • Be aware that slight differences may occur due to underlying parser implementations.

Examples

Handling Malformed HTML

const html = '<div>Unclosed div';
const json = converter.toJSON(html);
/* Output:
{
  tag: "div",
  children: ["Unclosed div"]
}
*/
// The parser corrects the unclosed <div> tag.

Enforcing Rules During Conversion

// Attempting to add children to a void element
const invalidJson = {
  tag: "br",
  children: ["Should not be here"]
};

try {
  converter.toHTML(invalidJson);
} catch (error) {
  console.error(error.message);
  // Output: Void element <br> cannot have children.
}

Using in Next.js (Client-Side)

"use client";

import { useState, useEffect } from 'react';
import { ClientHTMLJSONConverter } from 'html-json-converter/client';

export default function Demo() {
    const [htmlJSON, setHtmlJSON] = useState<string | null>(null);

    useEffect(() => {
        const converter = new ClientHTMLJSONConverter();
        const complexHTMLString = `<div>
                                    <h1>My Title</h1>
                                    <p>My paragraph</p>
                                    <div>
                                        <h2>My Subtitle</h2>
                                        <p>My sub paragraph</p>
                                    </div>
                                    <section style="color:red;">
                                        <h3>My Subtitle</h3>
                                        <p>My sub paragraph</p>
                                    </section>
                                    <img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" alt="Google Logo" />
                                    </div>`;
        const json = converter.toJSON(complexHTMLString);
        setHtmlJSON(JSON.stringify(json));
    }, []);

    return (
        <div className="max-w-5xl mx-auto text-left font-mono">
            {htmlJSON}
        </div>
    );
}

For Using in server side in Next.js

import { ServerHTMLJSONConverter } from 'html-json-converter/server';

export default async function Demo() {
    const complexHTMLString = `<div>
                                <h1>My Title</h1>
                                <p>My paragraph</p>
                                <div>
                                    <h2>My Subtitle</h2>
                                    <p>My sub paragraph</p>
                                </div>
                                <section style="color:red;">
                                    <h3>My Subtitle</h3>
                                    <p>My sub paragraph</p>
                                </section>
                                <img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" alt="Google Logo" />
                                </div>`;
    const converter = new ServerHTMLJSONConverter();
    const json = converter.toJSON(complexHTMLString);

    return (
        <div className="max-w-5xl mx-auto text-left font-mono">
            {JSON.stringify(json, null, 2)}
        </div>
    );
}

Note: Tested only for Next.js 14.2.11

Feedback and Contributions

I appreciate your feedback and contributions. If you encounter issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.