@vincentkoc/qrcode-tui

modern QR rendering helpers for Node.js CLIs and setup flows.

this package exists for the boring but important case where qrcode-terminal is stale, brittle, or just not worth trusting anymore.

it uses the maintained qrcode encoder underneath and exposes a small API for:

• terminal QR rendering
• UTF-8 QR rendering
• PNG data URLs
• base64 PNG payloads
• SVG rendering
• writing PNG files for headless or SSH flows
• writing SVG files for browser and docs flows

install

npm install @vincentkoc/qrcode-tui

usage

import {
  renderPngBase64,
  renderSvg,
  renderTerminal,
  renderUtf8,
  writePngFile,
  writeSvgFile,
} from "@vincentkoc/qrcode-tui";

const terminalQr = await renderTerminal("openclaw://pair?code=123", { small: true });
process.stdout.write(terminalQr);

const utf8Qr = await renderUtf8("openclaw://pair?code=123");
process.stdout.write(utf8Qr);

const pngBase64 = await renderPngBase64("openclaw://pair?code=123");
const svg = await renderSvg("openclaw://pair?code=123");
await writePngFile("openclaw://pair?code=123", "./pair.png");
await writeSvgFile("openclaw://pair?code=123", "./pair.svg");

cli

npx @vincentkoc/qrcode-tui "https://openclaw.ai"
npx @vincentkoc/qrcode-tui "https://openclaw.ai" --utf8
npx @vincentkoc/qrcode-tui "https://openclaw.ai" --svg
npx @vincentkoc/qrcode-tui "https://openclaw.ai" --png-base64
npx @vincentkoc/qrcode-tui --type png-data-url "https://openclaw.ai"
npx @vincentkoc/qrcode-tui "https://openclaw.ai" --out pair.png
echo "https://openclaw.ai" | npx @vincentkoc/qrcode-tui --utf8

api

renderTerminal(text, options?)

returns an ANSI terminal QR string.

renderUtf8(text, options?)

returns a UTF-8 block-character QR string.

renderPngDataUrl(text, options?)

returns a data:image/png;base64,... URL.

renderPngBase64(text, options?)

returns the base64 PNG payload without the data URL prefix.

renderSvg(text, options?)

returns an SVG document string.

writePngFile(text, filePath, options?)

writes a PNG file to disk and returns the file path. parent directories are created automatically.

writeSvgFile(text, filePath, options?)

writes an SVG file to disk and returns the file path. parent directories are created automatically.

cli flags

• --type terminal|utf8|png-base64|png-data-url|svg
• --out <path>
• --width <n>
• --scale <n>
• --margin <n>
• --error-correction <L|M|Q|H>
• --no-small
• --utf8
• --svg
• --png-base64
• --png-data-url

why not fork qrcode-terminal?

because the QR math is not the hard part here. the hard part is owning as little stale code as possible.

this package keeps the surface small and lets a maintained encoder do the real work.

why this package exists

this package is for a very specific annoying class of problem:

• setup flows that need scan-friendly QR output
• SSH or headless environments where terminal output still matters
• CLIs that want one small dependency seam for terminal, png, and svg QR output

it is intentionally small. the point is to own the rendering seam without owning a stale QR encoder forever.

license

MIT