html-entity-fixer

🔧 Fast, safe CLI tool for escaping unescaped HTML entities in modern web projects

✨ Features

• 🧠 Smart Tag Detection - Distinguishes between valid HTML/XML tags and text
• ⚛️ Component Support - Works with React components, custom elements, and XML
• 🚀 Fast - Optimized for large codebases and monorepos
• 🔒 Safe - Never double-escapes already-escaped entities
• 📁 Glob support - Process multiple files with patterns like src/**/*.jsx
• 👀 Dry-run mode - Preview changes before applying
• 🎛️ Configurable - Essential or extended escaping modes
• 📦 Lightweight - ~15KB package size, minimal dependencies

📦 Installation

# Global installation
npm install -g html-entity-fixer

# Local installation (recommended)
npm install --save-dev html-entity-fixer

🚀 Quick Start

# Fix all JSX files in src directory
html-entity-fixer "src/**/*.jsx"

# Preview changes without modifying files
html-entity-fixer "src/**/*.{jsx,tsx}" --dry-run

# Use extended mode for additional entities
html-entity-fixer "src/**/*.html" --mode extended

📖 Usage

html-entity-fixer <patterns...> [options]

Arguments

| Argument | Description | |----------|-------------| | patterns | Glob patterns for files to process (e.g., "src/**/*.jsx") |

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --dry-run | -d | Preview changes without modifying files | false | | --mode | -m | Escaping mode: essential or extended | essential | | --verbose | -v | Show detailed output | false | | --quiet | -q | Suppress all output except errors | false | | --version | | Show version number | | | --help | | Show help | |

🎯 Escaping Modes

Essential Mode (default)

Escapes the 5 critical HTML entities:

| Character | Entity | |-----------|--------| | & | & | | < | < | | > | > | | " | " | | ' | ' |

Extended Mode

Includes essential entities plus:

Includes essential entities plus common content writing symbols:

• Typography: © (©), ® (®), ™ (™), — (—), – (–), … (…), § (§), ¶ (¶), ° (°)
• Currency: € (€), £ (£), ¥ (¥), ¢ (¢)
• Fractions: ½ (½), ¼ (¼), ¾ (¾)
• Math: × (×), ÷ (÷), ± (±), ∞ (∞), ≠ (≠), ≈ (≈), ≤ (≤), ≥ (≥)
• Arrows: ← (←), → (→), ↑ (↑), ↓ (↓)
• Spacing: Non-breaking space ( )

🔧 Programmatic API

import { escapeHtml, processFiles } from 'html-entity-fixer';

// Escape a string
const result = escapeHtml("It's a <test>", 'essential');
console.log(result.content); // "It&#39;s a &lt;test&gt;"
console.log(result.escapedCount); // 3

// Process files
const summary = await processFiles(['src/**/*.jsx'], {
  mode: 'essential',
  dryRun: true,
});
console.log(`Found ${summary.totalEntitiesEscaped} entities to fix`);

🔄 CI/CD Integration

Use --dry-run in your CI pipeline to fail builds with unescaped entities:

# .github/workflows/lint.yml
- name: Check HTML entities
  run: npx html-entity-fixer "src/**/*.{jsx,tsx}" --dry-run

The command exits with code 1 if changes would be made.

📝 Commit Convention

This project uses Conventional Commits and semantic-release for automated versioning.

| Commit Type | Version Bump | Example | |-------------|--------------|---------| | fix: | Patch (0.0.x) | fix: handle edge case | | feat: | Minor (0.x.0) | feat: add extended mode | | feat!: or BREAKING CHANGE: | Major (x.0.0) | feat!: change API |

🤝 Contributing

See CONTRIBUTING.md for development setup and guidelines.

📄 License

MIT © Abhishek Panda