node-vc-500w

Node.js library and CLI for the Brother VC-500W color label printer (TCP/IP, port 9100).

Unofficial, MIT-licensed. Not affiliated with Brother Industries.

Install

pnpm add node-vc-500w
# or: npm install node-vc-500w
# or: yarn add node-vc-500w

Requires Node.js 22.18 or newer.

For CLI use:

pnpm add -g node-vc-500w
# or: npm install -g node-vc-500w

Quickstart — library

import { VC500W } from 'node-vc-500w';
import { readFile } from 'node:fs/promises';

await using printer = new VC500W({ host: '192.168.0.42' });
await printer.connect();

const jpeg = await readFile('label.jpg');
await printer.printJpeg(jpeg, { mode: 'vivid', cut: 'full' });
await printer.waitUntilIdle();

Quickstart — CLI

vc500w --host 192.168.0.42 status
vc500w --host 192.168.0.42 config --json
vc500w --host 192.168.0.42 print label.jpg --mode vivid --cut full --wait

Hardware notes

The VC-500W is a ZINK Zero-Ink full-color thermal label printer:

| Spec | Value | |---|---| | Print resolution | 313 dpi cross-web; 313 (color) / 317 (vivid) feed-direction | | Max print speed | 8 mm/s | | Max label length | 420 mm | | Max print width | 50 mm | | Cassette widths | 9, 12, 19, 25, 50 mm | | Cutter modes | none, half, full | | Connectivity | Wi-Fi 802.11 b/g/n, USB (this library uses Wi-Fi only) |

Protocol notes

The wire protocol carries <dataformat> values:

• jpeg — confirmed; what the official mobile app uses.
• rawrgb — confirmed; what the Brother CUPS backend (zsocket) uses with explicit width/height/quality/copies.
• Other values are not publicly documented. The low-level printer.print({ ... }) API accepts any string for experimentation.

Troubleshooting

Labels print but never cut. Some firmware revisions appear to require the TCP socket to close before the cutter engages. Set cutTriggerMode: 'close-reopen':

const printer = new VC500W({ host: '...', cutTriggerMode: 'close-reopen' });

Or from CLI: vc500w --host ... --cut-trigger close-reopen print ....

Connection drops after idle. The printer auto-sleeps. Keep-alive (30s default) usually prevents this; if it doesn't, periodically call getStatus() to wake it.

API surface

new VC500W(options: VC500WOptions)

printer.connect(): Promise<void>
printer.disconnect(): Promise<void>
printer.getConfiguration(): Promise<Configuration>
printer.getStatus(): Promise<Status>
printer.lock(): Promise<LockInfo>
printer.release(jobToken?: string): Promise<void>
printer.printJpeg(buf: Buffer, opts?: PrintJpegOptions): Promise<void>
printer.printRawRgb(buf: Buffer, opts: PrintRawRgbOptions): Promise<void>
printer.print(opts: PrintOptions): Promise<void>
printer.waitUntilIdle(opts?: { pollMs?: number; timeoutMs?: number }): Promise<void>

See type definitions in dist/index.d.ts for full option shapes.

License

MIT © 2026 Hanseulmaro Kim

Disclaimer

This is an unofficial library. Brother, VC-500W, and ZINK are trademarks of their respective owners. Use at your own risk; no warranty is provided.