Coming from term-img

paratext is a term-img alternative you adopt by changing one import. paratext/term-img is term-img 7's API: a file path or image bytes in, the inline image out. term-img's own test suite is the grade, and it passes every case.

Migrate from term-img: one importCopy Anchor Link

- import terminalImage, { UnsupportedTerminalError } from 'term-img';
+ import terminalImage, { UnsupportedTerminalError } from 'paratext/term-img';

  console.log(terminalImage('unicorn.jpg', { width: '50%' }));

Everything else stays: a path or a Uint8Array/Buffer; width, height, preserveAspectRatio and fallback; a missing or empty image throws a TypeError; an unsupported terminal calls your fallback or throws UnsupportedTerminalError, with term-img's message and name. Support is term-img's own terminal table — iTerm2 3+, WezTerm 20220319+, Konsole 22.04+, Rio 0.1.13+, VS Code 1.80+ — read from the environment, in term-img's order: the argument is checked, then the terminal, then the file is read. A path handed to an unsupported terminal reaches your fallback without the file being opened, as it does upstream. The Options type keeps its name and its FallbackType parameter, so a typed program compiles unchanged.

npx burgee migrate makes this edit for you: the row is level, so the codemod rewrites it (Migrate).

Is paratext compatible with term-img?Copy Anchor Link

Yes, and graded rather than claimed. term-img's own suite, vendored at 7.1.0 (the latest release) and unmodified apart from the import specifier, runs against paratext/term-img beside a control that runs it against real term-img:

From Compatibility, which npm run compat:page generates from the oracle's last run; that page is the authority. Until 2026-09-30 this row read 12 / 18: the six cases that hand a file path to a supported terminal failed, because paratext/term-img took bytes only. It now reads the path with node:fs, as term-img does. It is the one entry in paratext that does: the root and every other subpath touch nothing but strings, and a lock fails the build if node:fs reaches any of them.

What you gain over term-imgCopy Anchor Link

• Zero dependencies. term-img 7.1.0 depends on ansi-escapes and iterm2-version.
• iTerm2 10 and later are recognised. term-img reads iTerm2's major version from its first character, so it would read 10.2.1 as 1 and refuse the terminal; the façade parses the whole number. Nothing in the suite tells the two apart, so this is a fix that costs no compatibility.
• A file URL is a path too. term-img answers Image required to a URL; paratext/term-img reads it.
• A caption instead of a throw, when you want one. paratext's root image() — ansi-escapes' signature, plus caption — projects an image to its caption wherever support is absent or unknown, so a pipe or an agent reads text rather than an exception or raw escape bytes. The root takes bytes and never opens a file.

import { image } from 'paratext';

image(bytes, { caption: 'Build graph' });
// iTerm2, on a TTY: the inline image
// a pipe:           Build graph

When to switch from term-imgCopy Anchor Link

• You want term-img's behaviour without its two dependencies.
• Your output is also piped or read by an agent, and an image should become its caption there — the root image() does that.

The registry, the schema and the plugin host are on paratext.