Angular HTML Parser

10.5.0 verified Sun Apr 19 auth: no javascript

angular-html-parser is a JavaScript HTML parser directly extracted from the Angular framework's internal parsing engine, maintained by the Prettier organization. Currently at version 10.5.0, it receives frequent updates, typically syncing with changes made to the HTML parser within the main Angular repository. Its primary purpose is to provide a robust, Angular-compatible HTML parsing mechanism, often leveraged by tools like Prettier for formatting Angular templates. Key differentiators include added support for CDATA and DocType nodes, enhanced source span tracking for elements and attributes, and modifications to handle specific HTML syntax like bogus comments, going beyond a strict 1:1 replica of Angular's upstream parser. It supports Node.js environments version 14 and above.

Common errors

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause Attempting to access the `type` property on a parsed `Node` object after upgrading to version 10.0.0 or later.

fix

Replace node.type with node.kind in your code.

error ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/angular-html-parser/index.js ↓

cause Trying to `require()` the `angular-html-parser` package in a CommonJS module context, but the package is an ES Module.

fix

Change your require() statements to import statements (e.g., import { parse } from 'angular-html-parser';) and ensure your project is configured for ES Modules.

error SyntaxError: Unexpected token 'export' ↓

cause Running `angular-html-parser` in a Node.js environment older than version 14, which lacks full support for ES Modules.

fix

Upgrade your Node.js version to 14 or higher. You can use nvm install 16 and nvm use 16 to manage Node.js versions.

Warnings

breaking In version 10.0.0, the `type` property on parsed `Node` objects was renamed to `kind` for consistency. Code accessing `node.type` will now fail. ↓

fix Update all instances of `node.type` to `node.kind`.

gotcha This package requires Node.js version 14 or higher. Running it on older Node.js versions may lead to syntax errors or unexpected behavior due to ESM module usage and other modern JavaScript features. ↓

fix Ensure your Node.js environment is version 14 or later. Use a version manager like `nvm` to easily switch Node.js versions.

gotcha The parser frequently syncs with upstream changes from Angular's internal HTML parser. While this keeps it up-to-date, it means parsing behavior might subtly change across minor versions of `angular-html-parser` without an explicit 'breaking change' announcement if the upstream Angular parser was modified. ↓

fix Thoroughly test your parsing logic after any update, especially if you rely on very specific parsing behaviors or error reporting.

gotcha Although extracted from Angular, `angular-html-parser` includes its own set of modifications (e.g., support for CDATA, DocType, nameSpan, bogus comments). This means its behavior is not an exact 1:1 replica of Angular's internal parser. ↓

fix Consult the 'Modifications' section of the package's README to understand specific deviations from the upstream Angular parser if your use case demands strict Angular-like parsing.

Install

npm install angular-html-parser

yarn add angular-html-parser

pnpm add angular-html-parser

Imports

parse
wrong
```
const { parse } = require('angular-html-parser');
```
correct
```
import { parse } from 'angular-html-parser';
```
The package uses named exports and is designed for modern JavaScript environments (ESM). While CommonJS `require` might work in some setups, `import` is the recommended and future-proof approach.
Options
wrong
```
import { Options } from 'angular-html-parser';
```
correct
```
import type { Options } from 'angular-html-parser';
```
When using TypeScript, `Options` is a type definition. Use `import type` for clarity and to ensure it's removed during compilation if not used at runtime.
ParseTreeResult (and other Angular types)
```
import type { ParseTreeResult } from '@angular/compiler';
```
Types like `ng.ParseTreeResult` and `ng.TagContentType` mentioned in the API refer to Angular's internal types. For type safety, you might need to install `@angular/compiler` and import them directly from there if your project uses them explicitly, as they are not directly re-exported from `angular-html-parser` for public consumption.

Quickstart

Demonstrates how to parse a basic HTML string using the `parse` function, access the resulting root nodes, and handle potential parsing errors.

import { parse } from "angular-html-parser";

const htmlString = `
<!DOCTYPE html>
<html>
  <head>
    <title>Hello world!</title>
  </head>
  <body>
    <div>Hello world!</div>
  </body>
</html>
`;

const { rootNodes, errors } = parse(htmlString, {
  canSelfClose: false, // Example option
  isTagNameCaseSensitive: false // Example option
});

if (errors.length > 0) {
  console.error("Parsing errors:", errors);
} else {
  console.log("Parsed successfully. Root nodes:", rootNodes.length);
  // Example: access the first root node (<html>)
  if (rootNodes.length > 0 && rootNodes[0].kind === 'element') {
    console.log('First element tag name:', rootNodes[0].name);
  }
}