Skip to content

Commit 4255a10

Browse files
remarkablemarkremarkablemark
authored
Merge pull request #1123 from remarkablemark/refactor/typescript
refactor: migrate to TypeScript
2 parents 1fcb059 + 713c548 commit 4255a10

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+7172
-11649
lines changed

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
run: npm run lint
2323

2424
- name: Type check
25-
run: npm run lint:dts
25+
run: npm run lint:tsc
2626

2727
- name: Run unit tests
2828
run: npm run test:ci

‎.gitignore‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ jspm_packages
4141
.node_repl_history
4242

4343
# Build files
44-
build
45-
dist
44+
dist/
45+
lib/
4646

4747
# Vim swap files
4848
*.swp

‎.prettierrc.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
{
2-
"trailingComma": "none",
32
"singleQuote": true
43
}

‎README.md‎

Lines changed: 74 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ To replace an element with another element, check out the [`replace`](#replace)
2121

2222
#### Example
2323

24-
```js
25-
const parse = require('html-react-parser');
24+
```ts
25+
import parse from 'html-react-parser';
26+
2627
parse('<p>Hello, World!</p>'); // React.createElement('p', {}, 'Hello, World!')
2728
```
2829

@@ -43,6 +44,7 @@ parse('<p>Hello, World!</p>'); // React.createElement('p', {}, 'Hello, World!')
4344
- [htmlparser2](#htmlparser2)
4445
- [trim](#trim)
4546
- [Migration](#migration)
47+
- [v5](#v5)
4648
- [v4](#v4)
4749
- [v3](#v3)
4850
- [v2](#v2)
@@ -100,31 +102,31 @@ yarn add html-react-parser
100102

101103
Import ES module:
102104

103-
```js
105+
```ts
104106
import parse from 'html-react-parser';
105107
```
106108

107109
Or require CommonJS module:
108110

109-
```js
110-
const parse = require('html-react-parser');
111+
```ts
112+
const parse = require('html-react-parser').default;
111113
```
112114

113115
Parse single element:
114116

115-
```js
117+
```ts
116118
parse('<h1>single</h1>');
117119
```
118120

119121
Parse multiple elements:
120122

121-
```js
123+
```ts
122124
parse('<li>Item 1</li><li>Item 2</li>');
123125
```
124126

125127
Make sure to render parsed adjacent elements under a parent element:
126128

127-
```jsx
129+
```tsx
128130
<ul>
129131
{parse(`
130132
<li>Item 1</li>
@@ -135,15 +137,15 @@ Make sure to render parsed adjacent elements under a parent element:
135137

136138
Parse nested elements:
137139

138-
```js
140+
```ts
139141
parse('<body><p>Lorem ipsum</p></body>');
140142
```
141143

142144
Parse element with attributes:
143145

144-
```js
146+
```ts
145147
parse(
146-
'<hr id="foo" class="bar" data-attr="baz" custom="qux" style="top:42px;">'
148+
'<hr id="foo" class="bar" data-attr="baz" custom="qux" style="top:42px;">',
147149
);
148150
```
149151

@@ -153,19 +155,19 @@ The `replace` option allows you to replace an element with another element.
153155

154156
The `replace` callback's first argument is [domhandler](https://github.com/fb55/domhandler#example)'s node:
155157

156-
```js
158+
```ts
157159
parse('<br>', {
158-
replace: (domNode) => {
160+
replace(domNode) {
159161
console.dir(domNode, { depth: null });
160-
}
162+
},
161163
});
162164
```
163165

164166
<details>
165167
<summary>Console output</summary>
166168
<p>
167169

168-
```js
170+
```ts
169171
Element {
170172
type: 'tag',
171173
parent: null,
@@ -184,29 +186,43 @@ Element {
184186

185187
The element is replaced if a **valid** React element is returned:
186188

187-
```jsx
189+
```tsx
188190
parse('<p id="replace">text</p>', {
189-
replace: (domNode) => {
191+
replace(domNode) {
190192
if (domNode.attribs && domNode.attribs.id === 'replace') {
191193
return <span>replaced</span>;
192194
}
193-
}
195+
},
194196
});
195197
```
196198

197199
#### replace with TypeScript
198200

199-
For TypeScript projects, you may need to check that `domNode` is an instance of domhandler's `Element`:
201+
For TypeScript, you'll need to check that `domNode` is an instance of domhandler's `Element`:
200202

201203
```tsx
202204
import { HTMLReactParserOptions, Element } from 'html-react-parser';
203205

204206
const options: HTMLReactParserOptions = {
205-
replace: (domNode) => {
207+
replace(domNode) {
206208
if (domNode instanceof Element && domNode.attribs) {
207209
// ...
208210
}
209-
}
211+
},
212+
};
213+
```
214+
215+
Or use a type assertion:
216+
217+
```tsx
218+
import { HTMLReactParserOptions, Element } from 'html-react-parser';
219+
220+
const options: HTMLReactParserOptions = {
221+
replace(domNode) {
222+
if ((domNode as Element).attribs) {
223+
// ...
224+
}
225+
},
210226
};
211227
```
212228

@@ -216,7 +232,7 @@ If you're having issues take a look at our [Create React App example](./examples
216232

217233
Replace the element and its children (see [demo](https://replit.com/@remarkablemark/html-react-parser-replace-example)):
218234

219-
```jsx
235+
```tsx
220236
import parse, { domToReact } from 'html-react-parser';
221237

222238
const html = `
@@ -228,7 +244,7 @@ const html = `
228244
`;
229245

230246
const options = {
231-
replace: ({ attribs, children }) => {
247+
replace({ attribs, children }) {
232248
if (!attribs) {
233249
return;
234250
}
@@ -244,7 +260,7 @@ const options = {
244260
</span>
245261
);
246262
}
247-
}
263+
},
248264
};
249265

250266
parse(html, options);
@@ -273,20 +289,20 @@ parse(html, options);
273289

274290
Convert DOM attributes to React props with `attributesToProps`:
275291

276-
```jsx
292+
```tsx
277293
import parse, { attributesToProps } from 'html-react-parser';
278294

279295
const html = `
280296
<main class="prettify" style="background: #fff; text-align: center;" />
281297
`;
282298

283299
const options = {
284-
replace: (domNode) => {
300+
replace(domNode) {
285301
if (domNode.attribs && domNode.name === 'main') {
286302
const props = attributesToProps(domNode.attribs);
287303
return <div {...props} />;
288304
}
289-
}
305+
},
290306
};
291307

292308
parse(html, options);
@@ -307,9 +323,9 @@ parse(html, options);
307323

308324
[Exclude](https://replit.com/@remarkablemark/html-react-parser-56) an element from rendering by replacing it with `<React.Fragment>`:
309325

310-
```jsx
326+
```tsx
311327
parse('<p><br id="remove"></p>', {
312-
replace: ({ attribs }) => attribs && attribs.id === 'remove' && <></>
328+
replace: ({ attribs }) => attribs?.id === 'remove' && <></>,
313329
});
314330
```
315331

@@ -330,12 +346,12 @@ The `transform` option allows you to transform each element individually after i
330346

331347
The `transform` callback's first argument is the React element:
332348

333-
```jsx
349+
```tsx
334350
parse('<br>', {
335-
transform: (reactNode, domNode, index) => {
351+
transform(reactNode, domNode, index) {
336352
// this will wrap every element in a div
337353
return <div>{reactNode}</div>;
338-
}
354+
},
339355
});
340356
```
341357

@@ -345,15 +361,15 @@ The `library` option specifies the UI library. The default library is **React**.
345361

346362
To use Preact:
347363

348-
```js
364+
```ts
349365
parse('<br>', {
350-
library: require('preact')
366+
library: require('preact'),
351367
});
352368
```
353369

354370
Or a custom library:
355371

356-
```js
372+
```ts
357373
parse('<br>', {
358374
library: {
359375
cloneElement: () => {
@@ -364,8 +380,8 @@ parse('<br>', {
364380
},
365381
isValidElement: () => {
366382
/* ... */
367-
}
368-
}
383+
},
384+
},
369385
});
370386
```
371387

@@ -377,42 +393,50 @@ Default [htmlparser2 options](https://github.com/fb55/htmlparser2/wiki/Parser-op
377393

378394
To enable [`xmlMode`](https://github.com/fb55/htmlparser2/wiki/Parser-options#option-xmlmode):
379395

380-
```js
396+
```ts
381397
parse('<p /><p />', {
382398
htmlparser2: {
383-
xmlMode: true
384-
}
399+
xmlMode: true,
400+
},
385401
});
386402
```
387403

388404
### trim
389405

390406
By default, whitespace is preserved:
391407

392-
```js
408+
```ts
393409
parse('<br>\n'); // [React.createElement('br'), '\n']
394410
```
395411

396412
But certain elements like `<table>` will strip out invalid whitespace:
397413

398-
```js
414+
```ts
399415
parse('<table>\n</table>'); // React.createElement('table')
400416
```
401417

402418
To remove whitespace, enable the `trim` option:
403419

404-
```js
420+
```ts
405421
parse('<br>\n', { trim: true }); // React.createElement('br')
406422
```
407423

408424
However, intentional whitespace may be stripped out:
409425

410-
```js
426+
```ts
411427
parse('<p> </p>', { trim: true }); // React.createElement('p')
412428
```
413429

414430
## Migration
415431

432+
### v5
433+
434+
Migrated to TypeScript. CommonJS imports require the `.default` key:
435+
436+
```ts
437+
const parse = require('html-react-parser').default;
438+
```
439+
416440
### v4
417441

418442
[htmlparser2](https://github.com/fb55/htmlparser2) has been upgraded to [v9](https://github.com/fb55/htmlparser2/releases/tag/v9.0.0).
@@ -437,11 +461,11 @@ For the `replace` option, you may need to do the following:
437461
import { Element } from 'domhandler/lib/node';
438462

439463
parse('<br class="remove">', {
440-
replace: (domNode) => {
464+
replace(domNode) {
441465
if (domNode instanceof Element && domNode.attribs.class === 'remove') {
442466
return <></>;
443467
}
444-
}
468+
},
445469
});
446470
```
447471

@@ -490,8 +514,8 @@ Tags are lowercased by default. To prevent that from happening, pass the [htmlpa
490514
```js
491515
const options = {
492516
htmlparser2: {
493-
lowerCaseTags: false
494-
}
517+
lowerCaseTags: false,
518+
},
495519
};
496520
parse('<CustomElement>', options); // React.createElement('CustomElement')
497521
```
@@ -527,8 +551,8 @@ Then update your Webpack config to:
527551
module.exports = {
528552
// ...
529553
resolve: {
530-
mainFields: ['browser', 'main', 'module']
531-
}
554+
mainFields: ['browser', 'main', 'module'],
555+
},
532556
};
533557
```
534558

0 commit comments

Comments
 (0)