SOURCE_MAP_WARNING.md

Source Map Warnings - Solutions Guide

The Problem

The packages domutils, entities, and htmlparser2 (transitive dependencies of react-sanitized-html) have malformed source maps. Their sourceRoot points to GitHub URLs instead of local paths:

"sourceRoot": "https://raw.githubusercontent.com/fb55/domutils/0ab8bcf1ecfc70dfc93291a4cb2496578ac25e9c/src/"

This causes webpack's source-map-loader to fail with warnings during development.

Current Solution ✓ (Recommended)

Status: ✅ Implemented in webpack.config.js

We suppress these specific warnings using webpack's ignoreWarnings option.

Pros:

• ✅ Clean build output
• ✅ Simple and maintainable
• ✅ Doesn't affect your own code's source maps
• ✅ Standard practice for third-party dependency issues
• ✅ No performance impact

Cons:

• ⚠️ Hides warnings (but only for known broken packages)

Is this acceptable? YES, because:

1. The warnings are purely cosmetic - the code works perfectly
2. Source maps from dependencies aren't used when debugging your own code
3. These packages are mature and widely used (htmlparser2: 34M+ weekly downloads)
4. Major projects (React, Next.js, etc.) do the same thing

Alternative Solutions

1. Update to Latest Versions ⚠️

Current versions:

• domutils: 3.2.2 ← Already latest
• entities: 4.5.0 → 7.0.1 available
• htmlparser2: 8.0.2 → 10.1.0 available

How to implement: Add to package.json:

{
  "overrides": {
    "domutils": "^3.2.2",
    "entities": "^7.0.1",
    "htmlparser2": "^10.1.0"
  }
}

Pros:

• ✅ Might fix the issue if newer versions have correct source maps
• ✅ Get latest bug fixes

Cons:

• ⚠️ May introduce breaking changes
• ⚠️ May break react-sanitized-html compatibility
• ⚠️ Newer versions might still have the same issue
• ⚠️ Requires testing the entire application

Status: Not recommended without thorough testing

2. Use patch-package 🛠️

Manually fix the source maps and apply patches after npm install.

How to implement:

npm install patch-package --save-dev

# Fix the source map files manually
sed -i 's|"sourceRoot":"https://[^"]*"|"sourceRoot":""|g' \
  node_modules/domutils/lib/*.js.map \
  node_modules/entities/lib/*.js.map \
  node_modules/htmlparser2/lib/*.js.map

# Create patch
npx patch-package domutils entities htmlparser2

# Add to package.json scripts:
"postinstall": "patch-package"

Pros:

• ✅ Truly fixes the source maps
• ✅ Automated via postinstall hook

Cons:

• ❌ Complex setup and maintenance
• ❌ Patches may break on version updates
• ❌ Overkill for cosmetic warnings
• ❌ CI/CD overhead

Status: Overkill for this issue

3. Report Upstream 📢

File issues with package maintainers to fix their build configuration.

Repos:

• https://github.com/fb55/domutils
• https://github.com/fb55/entities
• https://github.com/fb55/htmlparser2

Pros:

• ✅ Benefits the entire community
• ✅ Proper long-term solution

Cons:

• ❌ No immediate fix
• ❌ Depends on maintainer response time
• ❌ May not be prioritized (it's just a warning)

Status: Worth doing, but doesn't solve your immediate problem

4. Replace react-sanitized-html 🔄

Switch to a different HTML sanitization library.

Alternatives:

• dompurify - Most popular (11M+ weekly downloads)
• sanitize-html directly (instead of via react wrapper)
• isomorphic-dompurify - Works in Node.js and browser

Example:

import DOMPurify from 'dompurify';

// Instead of:
// <SanitizedHTML html={content} />

// Use:
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(content) }} />

Pros:

• ✅ Completely avoids the problematic packages
• ✅ dompurify is industry standard
• ✅ Better performance

Cons:

• ❌ Code changes required
• ❌ Different API and configuration
• ❌ Migration effort

Status: Only worth it if you have other reasons to switch

5. Disable Source Maps in Development ❌

Remove --sourceMap from build scripts.

Pros:

• ✅ No warnings

Cons:

• ❌ Loses debugging capability for your own code
• ❌ Bad developer experience
• ❌ Not recommended

Status: Not recommended

Recommendation

Stick with the current solution (ignoreWarnings in webpack.config.js).

It's:

• ✅ Standard practice
• ✅ Zero maintenance
• ✅ No functional impact
• ✅ Keeps your build output clean
• ✅ Preserves source maps for your own code

Optional: File upstream issues to help the community, but don't block on them.

Testing

Verify source maps still work for your own code:

# Build in dev mode
jlpm build:labextension:dev

# Check that lib/*.js.map files are generated for YOUR code
ls -lh lib/*.js.map

# Open DevTools → Sources tab → you should see TypeScript files under webpack://

References

• Webpack ignoreWarnings: https://webpack.js.org/configuration/other-options/#ignorewarnings
• source-map-loader: https://webpack.js.org/loaders/source-map-loader/
• htmlparser2 issue tracker: https://github.com/fb55/htmlparser2/issues