diff --git a/.changeset/funny-dancers-battle.md b/.changeset/funny-dancers-battle.md new file mode 100644 index 00000000..4e22bed8 --- /dev/null +++ b/.changeset/funny-dancers-battle.md @@ -0,0 +1,7 @@ +--- +"@naverpay/safe-html-react-parser": major +--- + +Add a new package: safe-html-react-parser + +PR: [Add a new package: safe-html-react-parser](https://github.com/NaverPayDev/pie/pull/199) diff --git a/packages/safe-html-react-parser/README.md b/packages/safe-html-react-parser/README.md new file mode 100644 index 00000000..b3f08a55 --- /dev/null +++ b/packages/safe-html-react-parser/README.md @@ -0,0 +1,149 @@ +# safe-html-react-parser + +A secure wrapper for **html-react-parser** with **isomorphic-dompurify** that automatically sanitizes HTML before parsing. + +## What it does + +- ๐Ÿ›ก๏ธ **Security**: Automatically sanitizes malicious HTML using DOMPurify +- โš›๏ธ **React**: Seamlessly integrates with html-react-parser +- ๐ŸŒ **Universal**: Works in both browser and Node.js (SSR) environments +- ๐Ÿท๏ธ **Custom Tags**: Handles project-specific tags like `` safely + +## Requirements + +- Node.js >=20.19.5: isomorphic-dompurify@^2.30.1 + +## Installation + +```bash +npm install @naverpay/safe-html-react-parser +``` + +## Basic Usage + +```tsx +import { safeParse } from '@naverpay/safe-html-react-parser' + +// Basic usage - automatically sanitizes dangerous HTML +const Component = () => { + const maliciousHtml = '

Hello World

' + return
{safeParse(maliciousHtml)}
+} +// Result:

Hello World

+``` + +## API + +### `safeParse(htmlString, options?)` + +Parses HTML string into React elements with automatic XSS protection. + +#### Parameters + +- `htmlString` (string): The HTML string to parse +- `options` (SafeParseOptions, optional): Configuration options + +#### Options + +```typescript +interface SafeParseOptions extends HTMLReactParserOptions { + // DOMPurify configuration + sanitizeConfig?: DOMPurify.Config + + // Custom tags to preserve during sanitization + preserveCustomTags?: string[] +} +``` + +#### Returns + +React elements or array of React elements + +## Advanced Usage + +### Custom Sanitization Config + +```tsx +import { safeParse } from '@naverpay/safe-html-react-parser' + +const html = '

Text

' + +const result = safeParse(html, { + sanitizeConfig: { + ALLOWED_TAGS: ['div', 'p', 'style'], // Allow style tags + ALLOWED_ATTR: ['class'], + ALLOW_ARIA_ATTR: true + } +}) +``` + +### Preserving Custom Tags + +Use `preserveCustomTags` to preserve project-specific tags that would otherwise be removed: + +```tsx +import { safeParse } from '@naverpay/safe-html-react-parser' + +// Preserve custom tags like , , etc. +const svgContent = '' + +const result = safeParse(svgContent, { + preserveCustomTags: ['g', 'path'], + replace: (domNode) => { + if (domNode.name === 'g') { + return {/* custom rendering */} + } + if (domNode.name === 'path') { + return + } + } +}) +``` + +### Using with html-react-parser Options + +All html-react-parser options are supported: + +```tsx +import { safeParse } from '@naverpay/safe-html-react-parser' + +const html = '

Hello

test
' + +const result = safeParse(html, { + replace: (domNode) => { + if (domNode.name === 'img') { + return + } + }, + trim: true +}) +``` + +## Default Allowed Tags + +By default, the following HTML tags are allowed: + +```typescript +ALLOWED_TAGS: [ + 'p', 'br', 'strong', 'em', 'b', 'i', 'u', 'span', 'div', + 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'h', + 'ul', 'ol', 'li', 'dl', 'dt', 'dd', + 'a', 'img' +] +``` + +## Security Notes + +- All HTML is sanitized by DOMPurify before parsing +- Dangerous tags like `