Project Setup and Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• biome.json
• tsconfig.json
• README.md
• src/Parser.ts

The htmlparser2 project is a fast and forgiving HTML/XML parser built with TypeScript. The project setup is designed to support high-performance parsing through a streaming architecture while maintaining a robust development environment using modern tooling for linting, formatting, and testing.

The repository follows a standard Node.js module structure, utilizing ECMAScript modules (ESM) and providing type definitions for seamless integration in TypeScript projects. The build pipeline transforms source TypeScript files into optimized JavaScript distributed via the dist directory.

Sources: package.json:28 , README.md:9-12

Build and Package Configuration

The project is configured as a native ECMAScript module ("type": "module") and targets Node.js environments version 20.19.0 and higher. It employs a multi-entry point export strategy to provide access to the core parser as well as specialized stream implementations.

Export Structure

The project exports three primary paths:

• Root (.): The main entry point for the parser and DOM utilities.
• WebWritableStream: Implementation for Web Streams API.
• WritableStream: Implementation for Node.js Streams API.

Sources: package.json:28-44, package.json:88-90

TypeScript Configuration

The project uses TypeScript for development, targeting es2022 with nodenext module resolution. The configuration ensures strict type checking and generates declaration maps for better debugging in consuming applications.

The diagram above illustrates the transformation of source files in the src directory to the final distribution files in dist using the TypeScript compiler.
Sources: tsconfig.json:3-28, package.json:46-52

Development Scripts

htmlparser2 defines a set of scripts in package.json to manage the development lifecycle, including building, linting, formatting, and testing.

Script	Command	Purpose
build	tsc	Compiles the TypeScript source code into the dist directory.
format	npm run format:es && npm run format:biome	Runs both ESLint and Biome formatters to ensure code style consistency.
lint	npm run lint:es && npm run lint:ts && npm run lint:biome	Executes a comprehensive linting suite covering logic, types, and style.
test	npm run test:vi && npm run lint	Runs the test suite using Vitest followed by linting.
test:vi	vitest run	Executes unit and integration tests.
prepublishOnly	npm run build	Ensures the project is built before publishing to NPM.

Sources: package.json:53-65

Code Quality Tooling

The project utilizes Biome and ESLint for maintaining code quality. Biome is configured to handle formatting, linting, and import organization.

Biome Configuration

Biome is configured to use spaces for indentation (width: 4) and includes specific linting rules for performance and style, such as:

• Complexity: Disallowing useless string concatenations and enforcing simplified logic.
• Performance: Enforcing the use of top-level regular expressions.
• Style: Enforcing consistent array types, arrow returns, and object definitions.

Sources: biome.json:10-74

Linting Flow

The linting process is tiered to catch different types of issues:

1. Logic & Syntax: Handled by ESLint and Biome recommended rules.
2. Type Safety: Handled by tsc --noEmit using a specific ESLint-focused TS configuration.
3. Performance & Style: Handled by specific Biome rules.

Sources: package.json:57-61, biome.json:22-26

Project Dependency Graph

The project relies on a minimal set of core dependencies primarily focused on DOM handling and entity decoding, which are part of the same ecosystem.

The diagram shows the relationship between htmlparser2 and its core dependencies and development tools.
Sources: package.json:66-81, README.md:20-27

Summary of Environment Requirements

• Node.js: >= 20.19.0
• TypeScript: ^6.0.3
• VCS: Git (integration enabled in Biome)

Sources: package.json:89, package.json:79, biome.json:3-7