xxd-wasm

The classic xxd hex dump utility, compiled to WebAssembly. Works in browsers and Node.js.

Features

• Full xxd compatibility - All standard options supported
• Tiny size - Only 25KB WASM + 60KB JS
• Zero dependencies - Self-contained module
• TypeScript support - Full type definitions included
• Dual module - Works with CommonJS and ESM

Installation

npm install xxd-wasm

Quick Start

import { createXxd } from 'xxd-wasm';

const xxd = await createXxd();

// Write some data
xxd.FS.writeFile('/input.bin', new TextEncoder().encode('Hello, World!'));

// Run xxd
xxd.callMain(['/input.bin']);
// Output: 00000000: 4865 6c6c 6f2c 2057 6f72 6c64 21  Hello, World!

Usage

Capturing Output

let output = '';

const xxd = await createXxd({
    print: (text) => { output += text + '\n'; },
    printErr: (text) => { console.error(text); }
});

xxd.FS.writeFile('/data.bin', new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]));
xxd.callMain(['-p', '/data.bin']);

console.log(output); // "48656c6c6f\n"

Plain Hex Output

xxd.callMain(['-p', '/input.bin']);
// Output: 48656c6c6f2c20576f726c6421

C Include Format

xxd.callMain(['-i', '/image.png', '/image.h']);

const header = xxd.FS.readFile('/image.h', { encoding: 'utf8' });
// Output:
// unsigned char _image_png[] = {
//   0x89, 0x50, 0x4e, 0x47, ...
// };
// unsigned int _image_png_len = 1234;

Reverse: Hex to Binary

xxd.FS.writeFile('/hex.txt', '48656c6c6f');
xxd.callMain(['-r', '-p', '/hex.txt', '/output.bin']);

const binary = xxd.FS.readFile('/output.bin');
console.log(new TextDecoder().decode(binary)); // "Hello"

Binary Dump

xxd.callMain(['-b', '/input.bin']);
// Output: 00000000: 01001000 01100101 01101100 01101100 01101111  Hello

API Reference

createXxd(options?)

Creates an xxd instance.

Options:

• print(text: string) - Handler for stdout (default: console.log)
• printErr(text: string) - Handler for stderr (default: console.error)

Returns: Promise<XxdModule>

xxd.callMain(args: string[])

Run xxd with command-line arguments.

Returns: Exit code (0 = success)

xxd.FS.writeFile(path, data)

Write data to the virtual filesystem.

• path - File path (e.g., '/input.bin')
• data - string or Uint8Array

xxd.FS.readFile(path, options?)

Read a file from the virtual filesystem.

• path - File path
• options.encoding - Set to 'utf8' to return string

Returns: Uint8Array or string

xxd.FS.unlink(path)

Delete a file from the virtual filesystem.

Command-Line Options

| Option | Description | |--------|-------------| | -a | Toggle autoskip: * replaces nul-lines | | -b | Binary digit dump (bits instead of hex) | | -c cols | Format <cols> octets per line (default: 16) | | -C | Capitalize variable names in C output | | -d | Show offset in decimal instead of hex | | -e | Little-endian dump | | -E | Show characters in EBCDIC | | -g bytes | Group octets (default: 2) | | -i | Output in C include file style | | -l len | Stop after <len> bytes | | -n name | Set variable name for C output | | -o off | Add <off> to displayed offset | | -p | Plain hexdump style | | -r | Reverse: convert hex to binary | | -s seek | Start at <seek> bytes offset | | -u | Use uppercase hex letters |

Browser Usage

<script type="module">
import { createXxd } from 'https://unpkg.com/xxd-wasm/dist/xxd.mjs';

const xxd = await createXxd();
// ... use xxd
</script>

Or with a bundler:

import { createXxd } from 'xxd-wasm';

Node.js Usage

const { createXxd } = require('xxd-wasm');
// or
import { createXxd } from 'xxd-wasm';

const xxd = await createXxd();

// Read a real file
const fs = require('fs');
const data = fs.readFileSync('myfile.bin');

xxd.FS.writeFile('/myfile.bin', data);
xxd.callMain(['/myfile.bin']);

Building from Source

Requires Emscripten.

git clone https://github.com/avaitla/xxd-wasm.git
cd xxd-wasm

# Build everything
make all

# Or just the npm package
make npm

# Run tests
make test

Disclaimer

This project was created as a learning exercise to understand WebAssembly porting. The WebAssembly port, npm package, and web demo were primarily written by Claude (Anthropic's AI assistant), with human guidance and review.

License

Dual-licensed under MIT or GPL-2.0 (at your choice), same as the original xxd.

Original xxd by Juergen Weigert, with contributions from Bram Moolenaar et al.

Links

• npm package
• GitHub repository
• Original xxd source
• Live demo