node-unrtf
Version:
Asynchronous Node.js wrapper for the UnRTF conversion utility
133 lines (92 loc) • 4.45 kB
Markdown
> **Note**
> An UnRTF v0.19.3 binary is included as an optional dependency for Windows users via
> [node-unrtf-win32](https://github.com/Fdawgs/node-unrtf-win32). Due to its age, it has several issues,
> including the [inability to convert RTF documents generated from 2007 onwards](https://github.com/Fdawgs/node-unrtf/issues/83#issuecomment-855788586) and a [bug in the
> `noPictures` option that still generates pictures](https://github.com/Fdawgs/node-unrtf/issues/81).
>
> It is recommended that applications using the `node-unrtf` module run in a Linux environment with the
> latest available UnRTF binaries, which do not have these issues.
# node-unrtf
[](https://github.com/Fdawgs/node-unrtf/releases/latest)
[](https://www.npmjs.com/package/node-unrtf)
[](https://github.com/Fdawgs/node-unrtf/actions/workflows/ci.yml)
[](https://coveralls.io/github/Fdawgs/node-unrtf?branch=main)
[](https://github.com/prettier/prettier)
[](https://scorecard.dev/viewer/?uri=github.com/Fdawgs/node-unrtf)
> Asynchronous Node.js wrapper for the UnRTF conversion utility
## Overview
UnRTF is a command-line utility for manipulating RTF documents and extracting data from them, including converting RTF files to HTML or TXT.
The `node-unrtf` module provides an asynchronous Node.js wrapper around the UnRTF binary for easier use.
## Installation
Install using `npm`:
```sh
npm i node-unrtf
```
### Linux and macOS/Darwin support
For Linux and macOS users, the `unrtf` binary will need to be installed separately.
An example of downloading the binary on a Debian system:
```sh
sudo apt-get install unrtf
```
For macOS users, the binary can be installed with [Homebrew](https://brew.sh):
```sh
brew install unrtf
```
## Example usage
Please refer to the [JSDoc comments in the source code](./src/index.js) or the [generated type definitions](https://www.npmjs.com/package/node-unrtf?activeTab=code) for information on the available options.
### Async/await
Example of an `async`/`await` call to `unRtf.convert()` to convert an RTF file to HTML using ESM syntax:
```js
import { UnRTF } from "node-unrtf";
const file = "test_document.rtf";
const unRtf = new UnRTF();
const options = {
outputHtml: true,
};
const res = await unRtf.convert(file, options);
console.log(res);
```
### Promise chaining
Example of calling `unRtf.convert()` with a promise chain using CJS syntax:
```js
"use strict";
const { UnRTF } = require("node-unrtf");
const file = "test_document.rtf";
const unRtf = new UnRTF("/usr/bin");
const options = {
outputHtml: true,
};
unRtf
.convert(file, options)
.then((res) => {
console.log(res);
return res;
})
.catch((err) => {
console.error(err);
throw err;
});
```
### Removing images generated by UnRTF
As mentioned in the note block at the top of this README, the `noPictures` option does not remove images when used with UnRTF < v0.20.4 and will write them to the current working directory.
To remove images generated by UnRTF, it is recommended to use a globbing module such as [glob](https://www.npmjs.com/package/glob) in conjunction with the `node:fs/promises` module to find and remove them:
```js
import { unlink } from "node:fs/promises";
import { UnRTF } from "node-unrtf";
import { glob } from "glob";
const file = "test/files/test-rtf-complex.rtf";
const unRtf = new UnRTF();
const options = {
outputHtml: true,
noPictures: true,
};
await unRtf.convert(file, options);
const files = await glob("*.{emf,wmf}");
await Promise.all(files.map((fileD) => unlink(fileD)));
```
## Contributing
Contributions are welcome, and any help is greatly appreciated!
See [the contributing guide](https://github.com/Fdawgs/.github/blob/main/CONTRIBUTING.md) for details on how to get started.
Please adhere to this project's [Code of Conduct](https://github.com/Fdawgs/.github/blob/main/CODE_OF_CONDUCT.md) when contributing.
## License
`node-unrtf` is licensed under the [MIT](./LICENSE) license.