DEV Community: İlhan Neğiş

Built a Free Analytics Platform, Here's Why

İlhan Neğiş — Wed, 18 Mar 2026 06:12:07 +0000

The Problem That Bugged Me

I run my own sites, and every time I set up analytics, the same cycle repeated. Install Google Analytics, add a cookie banner, feel weird about handing over my visitors' browsing data to a company that already knows way too much about everyone. Try a privacy-friendly alternative, hit a paywall the moment traffic picks up. Rinse, repeat.

I figured there had to be a better way. Turns out, there wasn't, so I made one.

What Nanolytica Does

Nanolytica is privacy-first analytics that runs without cookies, without consent banners, and without storing any personal data. IPs get hashed, Do Not Track is honored, and the whole thing is GDPR and CCPA compliant by design, not bolted on as an afterthought.

You sign up, paste one script tag on your site, and that's it. Real-time dashboard, engagement tracking, scroll depth, referrer analysis, bot detection, it's all there from the start.

Why It's Free

Because I think basic analytics shouldn't cost money. No tiers, no plans, no "upgrade to unlock" nonsense. You get unlimited pageviews, up to 50 sites, CSV exports, real-time data, everything. No credit card required, ever.

I built this because I needed it. And if I needed it, I figured a lot of other people did too.

It's Also Open Source

The entire codebase is on GitHub under the MIT license. If you want to self-host it, clone the repo, build the single binary, and run it on your own server. Full control, no strings attached.

But most people just use the cloud version at nanolytica.org. Sign up takes 30 seconds and there's nothing to maintain on your end.

Who I Built This For

Indie developers, bloggers, small business owners, anyone running a side project, basically anyone who wants clean, honest analytics without the baggage. If you've been looking for a reason to move on from Google Analytics, I'd love for you to give Nanolytica a try.

It's free. It's private. And it's yours.

Head over to nanolytica.org and see what you think.

talkDOM: A Tiny Message-Passing Runtime for the DOM

İlhan Neğiş — Sat, 07 Mar 2026 13:33:05 +0000

Modern frontend development often assumes that building interactive web interfaces requires a heavy JavaScript framework. Over the years, frameworks have grown increasingly complex, introducing components, state management systems, build pipelines, and large runtime bundles.

talkdom.org

github

But the web already has a powerful platform: HTML + the DOM + HTTP.

The idea behind talkDOM is simple:

What if DOM elements could send messages to each other?

Instead of wiring JavaScript handlers everywhere, HTML becomes a small message-passing language. Elements act as senders and receivers, and interactions are expressed declaratively.

The result is a tiny runtime (only a few kilobytes) that enables fetching data, updating DOM fragments, composing pipelines, polling endpoints, and controlling navigation — all from HTML.

The Core Idea

In talkDOM, elements communicate using Smalltalk-style messages.

A sender contains a sender attribute:

<button sender="posts get:/posts | list apply:inner">
  Load Posts
</button>

And somewhere in the page there is a receiver:

<div receiver="list"></div>

When the button is clicked:

A message is sent to posts
A GET request is performed
The response is piped to list
The list's content is replaced

This message:

posts get:/posts | list apply:inner

can be read almost like a sentence:

"Posts, get /posts, then list apply the result as inner content."

Message Pipelines

One of the key features of talkDOM is message pipelines.

Multiple operations can be composed using |:

posts get:/posts | transform apply:json | list apply:inner

Each step can return a value (or a promise), which is passed to the next step in the pipeline.

This design is inspired by:

Unix pipes
Smalltalk keyword messages
message passing systems

Pipelines allow complex UI behaviors to be expressed with surprisingly little code.

Receivers

Receivers are simply DOM elements with a receiver attribute.

<div receiver="posts"></div>

Receivers can also belong to multiple groups:

<div receiver="toast error"></div>

Messages sent to toast will target all matching elements.

Receivers can optionally restrict what operations they accept:

<div receiver="posts" accepts="inner append text"></div>

This adds a small layer of safety to DOM updates.

Fetching and Updating Content

talkDOM provides built-in methods for HTTP requests and DOM updates.

Example:

<button sender="posts get:/posts apply:inner">
  Load
</button>

<div receiver="posts"></div>

Supported request methods:

get:
post:
put:
delete:

And update operations:

inner
append
text
outer

Server-Triggered Actions

Servers can trigger client-side actions using a response header:

X-TalkDOM-Trigger

Example response header:

X-TalkDOM-Trigger: toast apply:"Saved!" text

This allows the server to instruct the client to update UI elements without embedding JavaScript.

Polling

Receivers can automatically poll an endpoint.

<div receiver="feed get:/posts poll:5s"></div>

This will fetch /posts every 5 seconds and update the receiver.

Polling stops automatically if the element is removed from the DOM.

Navigation and History

talkDOM also supports history-aware navigation.

<a sender="page get:/posts apply:inner" push-url="/posts">
  Posts
</a>

When clicked:

The request is executed
The content is updated
The URL is pushed to browser history

Back/forward navigation replays the same message chain.

Persistence

Receivers can optionally persist their content in localStorage.

<div receiver="cart" persist></div>

After page reload, the content is restored automatically.

Events

talkDOM emits lifecycle events after operations:

talkdom:done
talkdom:error

Example:

document.addEventListener("talkdom:done", e => {
  console.log("operation finished", e.detail);
});

This makes it easy to hook into the runtime when needed.

Why Build This?

Projects like HTMX, Unpoly, and Turbo have shown that many interactive interfaces can be built without large frontend frameworks.

talkDOM explores a slightly different direction.

Instead of attribute-based APIs like:

hx-get="/posts"
hx-target="#list"
hx-swap="inner"

talkDOM uses a message syntax:

posts get:/posts apply:inner

This makes interactions:

composable
pipeline-friendly
closer to a programming language

HTML becomes a small DSL for UI behavior.

Design Goals

talkDOM was built with a few goals in mind:

Tiny runtime
No build step
Progressive enhancement
Composable interactions
Minimal JavaScript

The entire runtime is just a few hundred lines of JavaScript.

What This Is (and Isn’t)

talkDOM is not trying to replace full UI frameworks.

It is best suited for:

server-rendered applications
dashboards
admin panels
progressively enhanced pages

Where the server remains the primary source of truth.

Closing Thoughts

The web already provides a powerful programming model:

documents
events
HTTP
the DOM

Sometimes the best tool is not another abstraction layer, but a small runtime that lets the platform speak for itself.

talkDOM is an experiment in that direction: turning HTML into a tiny message-passing language for building interactive interfaces.

The project is available on GitHub:

https://github.com/eringen/talkdom

and you can see in action @ eringen.com

SSH Gaming: Turning a Login into a Level

İlhan Neğiş — Thu, 26 Feb 2026 16:29:09 +0000

I recently decided to experiment with OpenSSH's ForceCommand directive to see how far I could push a "headless" user experience. The result? XZAP, a terminal-based arcade game that you play by literally just SSHing into a server.

The Experiment

The goal was simple: test how to securely host a public interactive process without ever granting a user a shell. I wanted to see if I could create a seamless transition where the SSH handshake acts as the "Play" button.

By using the Match User and ForceCommand directives in sshd_config, I locked the gozap user directly into the game binary. When the user connects, the game starts; when they quit or die, the session drops. No bash, no filesystem access, just pure terminal logic.

How it Works

The game is written in Go, utilizing raw terminal mode to capture keypresses (W/A/S/D) and ANSI escape codes for rendering. It's lightweight, fast, and lives entirely in the buffer of your local terminal emulator.

The Stack

Language: Go (Golang)
Deployment: Linux (Ubuntu/Debian)
Gatekeeper: OpenSSH (with a hardened, shell-less configuration)

Why?

Honestly? Mostly for fun. There's something nostalgic about "BBS-style" access where the connection itself is the interface. It's a great way to test SSH security hardening while providing a 30-second distraction for anyone with a terminal.

If you have a terminal handy, give it a try:

ssh gozap@eringen.com

source: https://github.com/eringen/gozap^

No password required. Just gobble the berries and avoid the aliens.

Building a Pure Go WebP Encoder with Claude Code

İlhan Neğiş — Tue, 24 Feb 2026 09:31:34 +0000

I built gowebper, a pure Go WebP (VP8L) encoder. Zero dependencies, no CGo, no golang.org/x/image. Just Go and a spec. Claude Code wrote most of the implementation while I directed the architecture and debugged the gnarliest format bugs alongside it. Here's how it went, what broke, and what I learned.

Why?

Go's standard library can decode WebP but can't encode it. The only option is golang.org/x/image/webp, which is decode only too. If you want to create WebP files in Go, you're stuck reaching for CGo bindings to libwebp. I wanted something that could run anywhere Go runs: cross compiled, statically linked, no shared libraries.

VP8L (WebP lossless) seemed tractable. The spec is public, the format is well documented, and the bitstream is relatively straightforward compared to VP8 (the lossy variant). A Huffman coder, an LZ77 compressor, four image transforms, and a bit writer. How hard could it be?

The Architecture

The final codebase is about 3,000 lines of Go across six internal packages:

encode.go                        # main encoder, RIFF wrapper, transform orchestration
quantize.go                      # near lossless pre quantization
internal/bitwriter/              # LSB first bit packing (VP8L is LSB first, unlike most formats)
internal/colormodel/             # image.Image to packed ARGB uint32 with fast path type switches
internal/huffman/                # length limited canonical Huffman codes + VP8L tree serialization
internal/lz77/                   # hash chain LZ77 with VP8L's 2D spatial distance table
internal/transform/              # SubtractGreen, Predictor (14 modes), CrossColor (least squares)
internal/vp8ldec/                # reference decoder for round trip testing

Claude Code generated the initial implementation of each package from my descriptions of the VP8L spec. I'd describe a component, something like "implement canonical Huffman coding with a 15 bit length limit using a min heap", and it would produce working code on the first try. The boilerplate heavy parts (the 120 entry spatial distance table, the 14 predictor modes, the RLE code length encoding) were where it saved the most time.

The encoder supports 10 compression levels (0 through 9), progressively enabling more transforms and larger LZ77 windows. Level 0 is raw Huffman coded pixels. Level 9 uses all four transforms with a million pixel search window and color cache.

Where Things Got Interesting: The Bug Hunt

The initial implementation passed all internal round trip tests immediately. Encode an image, decode it with our own decoder, compare pixels. Perfect. I was feeling good.

Then I ran dwebp on the output:

Decoding of output.webp failed.
Status: 3(BITSTREAM_ERROR)

Every single file. Every level, every image. Our internal decoder was happy, but libwebp rejected everything. This started a multi day debugging session that taught me more about VP8L than I ever wanted to know.

Bug 1: The Missing Bit

The first bug was a single missing bit.

VP8L's bitstream has a flag called use_meta, a 1 bit field that signals whether the image uses meta Huffman coding (multiple Huffman tree groups for different image regions). We don't use meta Huffman, so the correct value is 0. But we weren't writing it at all.

This bit sits between the color cache flag and the Huffman tree data. Without it, dwebp would read our first Huffman tree bit as the meta Huffman flag, interpret it as "yes, use meta Huffman", and then try to parse a meta Huffman map from what was actually tree data. Instant corruption.

The subtle part: this flag only exists at the top level image (what libwebp calls is_level0). Transform sub images (predictor tile data, palette data) don't have it. So you can't just "always write it". You need to know your context.

I found it by fetching the libwebp source code and reading ReadHuffmanCodes(). One line: VP8LReadBits(br, 1), right there, between color cache and tree reading, guarded by if (is_level0). Claude Code had faithfully implemented the VP8L spec but missed this detail because the spec buries it in prose that's easy to skim past.

The fix: one line of code. bw.WriteBits(0, 1). In two places.

After this fix, small images (1x1, 2x2, up to about 200x200) decoded perfectly with dwebp. But test.png (387x429, a real photo) still failed.

Bug 2: The Undercomplete Huffman Tree

VP8L limits Huffman code lengths to 15 bits. When the naive Huffman algorithm produces codes longer than 15 bits (which happens with skewed frequency distributions), you need to "limit" the tree: shorten the deepest codes and redistribute the code space.

This redistribution must maintain Kraft equality: the sum of 2^(length) across all codes must equal exactly 1. If it's less than 1, the code is "undercomplete" (there are unused bit patterns) and libwebp rejects it.

Our limitLengths function had a greedy loop that would lengthen codes (increase depth) to reduce the Kraft sum after clamping. But each lengthening step reduces the sum by a power of 2, and the loop processed all eligible codes in a single pass. For a tree with 225 active symbols, this could overshoot. The Kraft sum would end up at 32,767 instead of 32,768 (undercomplete by 1).

Binary search revealed the exact threshold: rows=280 of test.png worked, rows=281 failed. At row 281, the green channel tree had enough symbols that limitLengths would overshoot.

The fix: Replace the entry based greedy algorithm with a bit count based approach. Process depths from shallowest to deepest (largest reduction first), using integer division to guarantee exact Kraft equality. It's essentially the binary decomposition of the excess, like making change with powers of 2 coins.

Bug 3: The Spatial Distance Table

With the Kraft fix, Level 0 (no LZ77) worked perfectly at all image sizes. But Levels 1 through 6 (with LZ77 backward references) still failed.

VP8L uses a 2D spatial distance table for encoding backward reference distances. Instead of storing "120 pixels back", you store a plane code that the decoder maps to a (dx, dy) offset. The first 120 plane codes have predefined spatial offsets:

plane code 1 = (dx=0, dy=1)   pixel directly above
plane code 2 = (dx=1, dy=0)   pixel to the left
plane code 3 = (dx=1, dy=1)   pixel above right
plane code 4 = (dx=-1, dy=1)  pixel above left
...

Our encoder assumed that pixel distances 1 through 4 mapped directly to plane codes 1 through 4. They don't. Plane code 1 is the pixel above (distance = image width), not the pixel to the left (distance = 1). Plane code 2 is the pixel to the left.

This meant every single backward reference with a small distance was pointing to the wrong pixel. Our internal decoder had the same bug in reverse, so round trip tests passed. Both sides were wrong in the same way. But dwebp uses the correct mapping.

The fix: Include all 120 spatial table entries in the reverse lookup (we were only using entries 5 through 120), and remove the special case for small distances. Also fix the internal decoder to match.

Working with Claude Code

The pattern that worked best: I'd describe the architecture and constraints, Claude Code would generate the implementation, and then I'd test against external tools (dwebp, cwebp, Pillow). When something failed, I'd direct the investigation. "Binary search for the failing image size." "Compare our bitstream against cwebp's output byte by byte." "Fetch the libwebp source and find where it reads the meta Huffman flag." Claude Code would execute.

Claude Code was excellent at:

Generating boilerplate heavy code. The 120 entry distance table, 14 predictor modes, RLE code length encoding.
Implementing well specified algorithms. Huffman tree construction, canonical code assignment, LZ77 hash chains.
Writing targeted debugging tools. Bit level comparators, Kraft sum validators, binary search test harnesses.
Iterating quickly. Modifying code, running tests, analyzing output in tight loops.

The challenges were all in format compatibility: the gaps between the spec as written and the spec as implemented by libwebp. These required reading the actual libwebp C source code and understanding the decoder's expectations, not just the encoder's intent.

The Numbers

For test.png (387x429 RGBA):

Level	Quality	Size	Notes
0	0 (lossless)	277 KB	Baseline
6	0 (lossless)	104 KB	Competitive
9	0 (lossless)	121 KB	Diminishing returns
6	50	52 KB	Near lossless sweet spot
6	25	41 KB	Visible loss, small file

All output validates with dwebp 1.6.0.

Takeaways

Internal round trip tests are necessary but not sufficient. If both your encoder and decoder share a bug, your tests will pass and your output will be wrong. Always test against an external reference decoder.
Binary search is the most underrated debugging technique. "Works at 280 rows, fails at 281" is infinitely more useful than "fails on large images". Same for isolating which feature flag causes the failure.
A single missing bit can corrupt everything downstream. Bit packed formats have no error recovery. One missing bit shifts every subsequent field by one position, and the decoder interprets garbage until it gives up.
LLMs are great at implementing specs, less great at catching spec ambiguities. The VP8L spec says there's a meta Huffman flag but doesn't emphasize that it only appears at level 0. Claude Code implemented what the spec says; the bug was in what the spec implies.
Pure Go implementations are worth the effort. No CGo means easy cross compilation, no shared library headaches, simpler deployment, and full control over the code. The performance is reasonable: encoding a 387x429 image at level 6 takes about 50ms on an M series Mac.

The code is at github.com/eringen/gowebper. go get github.com/eringen/gowebper@v0.1.1 and you're encoding WebP files in pure Go.

Barcode Scanning on iOS: The Missing Web API and a WebAssembly Solution

İlhan Neğiş — Tue, 24 Feb 2026 09:28:29 +0000

If you've ever tried to build a web based barcode scanner targeting iOS, you've likely hit a wall: Safari doesn't support the Barcode Detection API^.

tldr; Live demo: https://eringen.com/workbench/wasm-barcode/^ (NPM version)

source version: https://eringen.com/workbench/wasm-barcode/index2.html^ (With rotation passes visible)

The Problem

The Barcode Detection API is part of the Shape Detection API spec and provides a clean, native way to detect barcodes from images or camera feeds in the browser. Chrome on Android has supported it for a while, but Safari and by extension every browser on iOS, since they all use WebKit under the hood simply doesn't implement it.

This means any web app relying on BarcodeDetector will silently fail on iPhones and iPads. For projects that need crossplatform barcode scanning without a native app, this is a dealbreaker.

The Usual Workarounds

Most JavaScript barcode libraries tackle this with pure JS decoding. They work, but the performance cost is noticeable especially on older iOS devices where you need smooth, realtime scanning from a camera feed. Dropped frames and slow detection make for a poor user experience.

A WebAssembly Approach

Instead of decoding barcodes in JavaScript, we can compile a proven C library ZBar^ to WebAssembly using Emscripten. ZBar has been around for years and handles a wide range of barcode formats reliably.

The workflow is straightforward:

Capture camera frames using getUserMedia
Crop to a region of interest and convert to grayscale in JavaScript
Pass the pixel data to ZBar running in WebAssembly
Get back the decoded barcode type, data, and bounding polygon

Because the heavy lifting happens in compiled WASM rather than interpreted JavaScript, the performance is near native. On iOS devices, this translates to fast, responsive scanning that feels like a native app.

From Prototype to Production

A big shout out to Berkley Wolf and his blog post, I was able to cobble together a prototype quickly, pay him a visit: Using the ZBar barcode scanning suite in the browser with WebAssembly^

The initial prototype worked, but it was a single index.js file with global state, parseInt for rounding, implicit globals, and a static PNG overlay. Useful for proving the concept, not so much for shipping in a real app or embedding in a React/Vue project.

Here's what the modernization looked like.

TypeScript + Vite

The codebase moved from a plain <script> tag to TypeScript with strict: true and noImplicitAny, built with Vite. The Emscripten generated a.out.js stays as a classic script (it needs to land on window.Module), but everything else is typed. A src/types/emscripten.d.ts file declares the subset of the Emscripten API we use: cwrap, HEAP8, HEAP32, UTF8ToString, and the custom processResult callback.

This caught real bugs during the port. For example, the original code did parseInt(cameraWidth * 0.702) where Math.floor was the correct operation, parseInt expects a string. TypeScript flagged these immediately.

Animated CSS Overlay

The original project used a static barcodelayout.png image positioned over the video to show the scan region. The new version replaces it with a programmatic overlay: four dark mask divs surrounding a transparent scan region, "L" shaped corner brackets, and a sweeping laser line, all pure CSS with a @keyframes animation. The overlay injects its styles via a single deduplicated <style> tag and positions everything using CSS custom properties derived from the scan region dimensions.

This eliminates an external asset, scales to any container size, and gives users clear visual feedback that something is actively scanning.

The `BarcodeScanner` Class

The core of the rewrite is a single exportable class:

const scanner = new BarcodeScanner({
  container: document.getElementById('scanner-mount')!,
  onDetect: (result) => console.log(result.symbol, result.data),
});

await scanner.start();
// later...
scanner.stop();

The constructor stores configuration only, no side effects. This matters for React strict mode, which double invokes effects in development. start() handles the full initialization chain: DOM setup, WASM loading, camera acquisition, result handler wiring, and the scan interval. stop() tears everything down cleanly including stopping camera tracks, something the original code never did.

The class is designed to be wrapped. A React component is just a useEffect that calls start() and returns stop():

useEffect(() => {
  const scanner = new BarcodeScanner({
    container: ref.current!,
    onDetect: (result) => onScan(result.data),
  });
  scanner.start();
  return () => scanner.stop();
}, [onScan]);

Rotation Based Skew Correction

In the real world, users don't hold barcodes perfectly straight. The original scanner only looked at 0 degrees, meaning a slight tilt could cause a miss.

The new scan loop tries three angles per tick: 0 degrees, +30 degrees, and -30 degrees. The key insight is that this can use early exit. If ZBar finds a barcode at 0 degrees, we skip the rotated passes entirely. Most scans only need one pass. The rotation itself is just a Canvas 2D translate-rotate-translate transform before drawing the video frame to the offscreen canvas:

// Rotate around the center of the offscreen canvas
ctx.translate(w / 2, h / 2);
ctx.rotate(angle);
ctx.translate(-w / 2, -h / 2);

// Draw the video crop (now rotated)
ctx.drawImage(video, srcX, srcY, srcW, srcH, 0, 0, w, h);

The rotation cost is minimal since we're only rotating a small cropped region (roughly 700 by 240 pixels), not the full camera frame.

A WASM Memory Pitfall

One bug that took some digging: the original code allocated a new WASM heap buffer every scan tick but never freed it. A memory leak, but it worked because ZBar's zbar_image_free_data callback actually freed the buffer when the image was destroyed at the end of scan_image.

The modernized version initially tried to be clever by allocating one buffer and reusing it. This was use after free: ZBar freed the buffer at the end of the first scan_image call, and every subsequent write to that pointer corrupted the WASM heap. It would run for about 70 seconds (around 475 successful scans) before crashing with RuntimeError: memory access out of bounds.

The fix was simple: allocate a fresh buffer per scan_image call, matching the original behavior. ZBar handles cleanup. The lesson: when bridging JS and WASM, understand who owns the memory. In scan.c:

// This registers zbar_image_free_data as the cleanup handler.
// When zbar_image_destroy runs, it calls free() on our buffer.
zbar_image_set_data(image, raw, width * height, zbar_image_free_data);

Video Resolution Scaling

Another subtle fix: the original code assumed the camera delivered exactly 2x the container size. It requested 1000x1000 for a 500x500 container and hardcoded barcodeOffset * 2 as the drawImage source coordinates. If the camera returned a different resolution (common across devices), the crop region was wrong.

The new code reads video.videoWidth and video.videoHeight each tick and computes a proper scale factor:

const scaleX = videoW / this.cameraWidth;
const scaleY = videoH / this.cameraHeight;
const srcX = this.barcodeOffsetX * scaleX;

This works regardless of the actual camera resolution.

Debug Preview Panel

For development and troubleshooting, the scanner accepts an optional previewCanvas element. When provided, it renders all three rotation passes stacked vertically in real time. The angle that detected a barcode gets a green border. This makes it trivial to see exactly what ZBar is processing at each angle, useful both for development and for demos.

Results

In practice, the WASM scanner detects barcodes within a couple of frames on modern iPhones. The scan loop runs at roughly 150ms intervals, and ZBar's processing time per frame is negligible. Combined with the animated overlay, audio feedback on detection, and rotation based skew correction, the experience is smooth enough that users won't notice they're using a web app.

The rotation passes add real value. In testing, barcodes tilted at around 25-30 degrees that the original scanner missed entirely are now caught on the second or third pass of the same tick.

What's Supported

ZBar handles most common 1D formats (EAN-13, EAN-8, UPC-A, UPC-E, Code 128, Code 39, Code 93, ISBN, Interleaved 2 of 5, DataBar) and QR codes. It does not support Data Matrix, PDF417, or Aztec. For those, you'd need a different WASM library like ZXing.

Takeaway

Until Apple adds Barcode Detection API support to Safari, WebAssembly is the best path to performant barcode scanning on iOS. By leveraging real world tested C libraries through WASM, we get reliability and speed without waiting for browser vendors to catch up.

The TypeScript rewrite makes the scanner embeddable in any modern frontend stack. The BarcodeScanner class handles the full lifecycle, camera permissions, WASM initialization, scan loop, cleanup, so your framework wrapper only needs to call start() and stop().

The full source is available at https://github.com/eringen/web-wasm-barcode-reader^.

NPM package: https://www.npmjs.com/package/web-wasm-barcode-reader^

npm i web-wasm-barcode-reader

Usage as npm Package

The library requires the Emscripten WASM glue script (a.out.js) to be loaded before the scanner is started. The WASM binary (a.out.wasm) is fetched automatically by the glue script at runtime.

Copy the WASM files into your public/static directory After installing, copy the WASM assets to a location your web server can serve:

cp node_modules/web-wasm-barcode-reader/public/a.out.js  public/
cp node_modules/web-wasm-barcode-reader/public/a.out.wasm public/

Serve index.html as show.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Barcode Scanner</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }

    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      background: #0f172a;
      color: #e2e8f0;
      min-height: 100vh;
      display: flex;
      flex-direction: column;
      align-items: center;
    }

    h1 {
      margin: 1.5rem 0 1rem;
      font-size: 1.5rem;
      font-weight: 600;
    }

    #scanner-container {
      width: 100%;
      max-width: 480px;
      aspect-ratio: 1;
      background: #1e293b;
      border-radius: 12px;
      overflow: hidden;
      position: relative;
    }

    #controls {
      display: flex;
      gap: 0.75rem;
      margin: 1rem 0;
    }

    button {
      padding: 0.6rem 1.4rem;
      border: none;
      border-radius: 8px;
      font-size: 0.95rem;
      font-weight: 500;
      cursor: pointer;
      transition: background 0.2s;
    }

    #start-btn {
      background: #22c55e;
      color: #fff;
    }
    #start-btn:hover { background: #16a34a; }
    #start-btn:disabled { background: #4b5563; cursor: not-allowed; }

    #stop-btn {
      background: #ef4444;
      color: #fff;
    }
    #stop-btn:hover { background: #dc2626; }
    #stop-btn:disabled { background: #4b5563; cursor: not-allowed; }

    #torch-btn {
      background: #eab308;
      color: #1e293b;
    }
    #torch-btn:hover { background: #ca8a04; }
    #torch-btn:disabled { background: #4b5563; color: #9ca3af; cursor: not-allowed; }

    #results {
      width: 100%;
      max-width: 480px;
      margin-bottom: 2rem;
    }

    #results h2 {
      font-size: 1.1rem;
      margin-bottom: 0.5rem;
      color: #94a3b8;
    }

    #result-list {
      list-style: none;
      display: flex;
      flex-direction: column;
      gap: 0.5rem;
    }

    .result-item {
      background: #1e293b;
      border: 1px solid #334155;
      border-radius: 8px;
      padding: 0.75rem 1rem;
      display: flex;
      justify-content: space-between;
      align-items: center;
      animation: fadeIn 0.3s ease;
    }

    .result-item .data {
      font-family: "SF Mono", "Fira Code", monospace;
      font-size: 0.95rem;
      word-break: break-all;
    }

    .result-item .type {
      font-size: 0.75rem;
      background: #334155;
      padding: 0.2rem 0.5rem;
      border-radius: 4px;
      color: #94a3b8;
      white-space: nowrap;
      margin-left: 0.75rem;
    }

    .result-item .copy-btn {
      background: none;
      border: 1px solid #475569;
      color: #94a3b8;
      padding: 0.3rem 0.6rem;
      font-size: 0.75rem;
      border-radius: 4px;
      margin-left: 0.5rem;
      flex-shrink: 0;
    }
    .result-item .copy-btn:hover { background: #334155; color: #e2e8f0; }

    #status {
      font-size: 0.85rem;
      color: #64748b;
      margin-bottom: 0.5rem;
      min-height: 1.2em;
    }

    @keyframes fadeIn {
      from { opacity: 0; transform: translateY(-4px); }
      to { opacity: 1; transform: translateY(0); }
    }
  </style>
</head>
<body>
  <h1>Barcode Scanner</h1>
  <p id="status">Press Start to begin scanning</p>

  <div id="scanner-container"></div>

  <div id="controls">
    <button id="start-btn">Start</button>
    <button id="stop-btn" disabled>Stop</button>
    <button id="torch-btn" disabled>Torch</button>
  </div>

  <div id="results">
    <h2>Scanned Results</h2>
    <ul id="result-list"></ul>
  </div>

  <!-- Emscripten glue must load as a classic script before the module -->
  <script>
    var Module = {
      locateFile: function(path) {
        return '/public/' + path;
      }
    };
  </script>
  <script src="/public/a.out.js"></script>
  <script type="module">
    import { BarcodeScanner } from './public/web-wasm-barcode-reader.js';

    const container = document.getElementById('scanner-container');
    const startBtn = document.getElementById('start-btn');
    const stopBtn = document.getElementById('stop-btn');
    const torchBtn = document.getElementById('torch-btn');
    const resultList = document.getElementById('result-list');
    const status = document.getElementById('status');

    let scanner = null;
    const seenCodes = new Set();

    function addResult(result) {
      // Deduplicate consecutive identical scans
      const key = result.symbol + ':' + result.data;
      if (seenCodes.has(key)) return;
      seenCodes.add(key);

      const li = document.createElement('li');
      li.className = 'result-item';

      const dataSpan = document.createElement('span');
      dataSpan.className = 'data';
      dataSpan.textContent = result.data;

      const typeSpan = document.createElement('span');
      typeSpan.className = 'type';
      typeSpan.textContent = result.symbol;

      const copyBtn = document.createElement('button');
      copyBtn.className = 'copy-btn';
      copyBtn.textContent = 'Copy';
      copyBtn.addEventListener('click', () => {
        navigator.clipboard.writeText(result.data).then(() => {
          copyBtn.textContent = 'Copied!';
          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
        });
      });

      li.appendChild(dataSpan);
      li.appendChild(typeSpan);
      li.appendChild(copyBtn);
      resultList.prepend(li);
    }

    startBtn.addEventListener('click', async () => {
      startBtn.disabled = true;
      status.textContent = 'Starting camera...';

      scanner = new BarcodeScanner({
        container,
        onDetect: (result) => {
          addResult(result);
          status.textContent = `Detected: ${result.symbol} - ${result.data}`;
        },
        onError: (err) => {
          status.textContent = 'Error: ' + err.message;
          console.error(err);
        },
        beepOnDetect: true,
        facingMode: 'environment',
      });

      try {
        await scanner.start();
        status.textContent = 'Scanning... point camera at a barcode';
        stopBtn.disabled = false;
        torchBtn.disabled = false;
      } catch (err) {
        status.textContent = 'Failed to start: ' + err.message;
        startBtn.disabled = false;
        scanner = null;
      }
    });

    stopBtn.addEventListener('click', () => {
      if (scanner) {
        scanner.stop();
        scanner = null;
      }
      startBtn.disabled = false;
      stopBtn.disabled = true;
      torchBtn.disabled = true;
      status.textContent = 'Scanner stopped';
    });

    torchBtn.addEventListener('click', async () => {
      if (!scanner) return;
      try {
        const on = await scanner.toggleTorch();
        torchBtn.textContent = on ? 'Torch Off' : 'Torch';
      } catch (err) {
        status.textContent = 'Torch not supported on this device';
      }
    });
  </script>
</body>
</html>

Browser Based Passport MRZ Reader with Tesseract.js

İlhan Neğiş — Tue, 24 Feb 2026 09:27:47 +0000

Why

This project was born out of a real world need: VAT refund processing for tourists shopping in Dubai. When visitors make purchases in the UAE, they're eligible for VAT returns but claiming that refund requires passport verification at the point of sale. Rather than manually typing passport details (slow, error-prone, and frustrating for both staff and customers), we needed a fast, accurate way to capture document data directly.

tldr link: https://github.com/eringen/web-mrz-reader^
demo: https://eringen.com/workbench/web-mrz-reader/^

What started as a passport-only reader quickly evolved. Customers presented national ID cards, residence permits, and various travel documents all with machine readable zones, but in different formats. That's when we expanded the reader to support all three ICAO document types.

What

The Machine Readable Zone^ is a standardized format defined by ICAO (International Civil Aviation Organization) in Doc 9303^. It's the block of text printed in the OCR-B font at the bottom of passports, ID cards, and travel documents. Every international border checkpoint in the world can read it.

ICAO defines three MRZ formats, each designed for a different document size:

TD3 Passports

The most familiar format. Two lines, 44 characters each, totaling 88 characters.

P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<
L898902C36UTO7408122F1204159ZE184226B<<<<<10

Line 1 carries the document type (P for passport), issuing country, and the holder's name. Line 2 packs in the passport number, nationality, date of birth, gender, expiration date, personal number, and five check digits.

TD1 ID Cards

The most compact format, used on credit-card-sized ID documents. Three lines, 30 characters each, totaling 90 characters.

I<UTOD231458907<<<<<<<<<<<<<<<
7408122F1204159UTO<<<<<<<<<<<6
ERIKSSON<<ANNA<MARIA<<<<<<<<<<

TD1 distributes data across three shorter lines. Line 1 holds the document type, country, document number, and optional data. Line 2 carries dates, gender, nationality, and more optional data. Line 3 is dedicated entirely to the holder's name. This separation makes TD1 the only format where the name lives on its own line.

TD2 Travel Documents

A middle format for larger-than-ID-card but smaller-than-passport documents. Two lines, 36 characters each, totaling 72 characters.

I<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<
D231458907UTO7408122F1204159<<<<<<06

TD2 is structured like TD3 but narrower the name shares line 1 with the document type and country, while line 2 mirrors the TD3 layout in a compressed form.

Comparing the Three Formats

	TD1 (ID Card)	TD2 (Travel Doc)	TD3 (Passport)
Lines	3	2	2
Chars/line	30	36	44
Total	90	72	88
Name location	Line 3	Line 1	Line 1
Check digits	4	4	5
Doc type prefix	`I<`, `A<`, `C<`	`I<`, `A<`, `C<`	`P<`

All three formats share the same check digit algorithm but apply it to different field positions. TD3 has an extra check digit for the personal number field, which TD1 and TD2 don't have.

The Challenge

Traditional MRZ readers require specialized hardware infrared scanners or dedicated OCR devices costing thousands. We wanted something different: a solution that works with any smartphone or laptop camera, runs entirely in the browser, handles all three document formats, and keeps sensitive data private by never sending it to a server.

Our Approach

The entire solution is built with vanilla Javascript no frameworks, no build process, no bundler required. Just plain HTML and Javascript files served directly. This keeps the project simple, auditable, and eliminates tooling complexity.

1. Tesseract.js with Custom Training

The backbone is Tesseract.js^, a Javascript port of the Tesseract OCR engine compiled to WebAssembly. The default English model struggles with MRZ because MRZ uses the OCR-B font and only 37 possible characters (A-Z, 0-9, <).

We trained a custom model specifically for MRZ recognition. This dramatically improved accuracy, especially for commonly confused characters:

0 (zero) vs O (letter O)
1 (one) vs I (letter I)
< (filler) vs K or X

2. Multi-Format Detection

The first challenge with supporting multiple formats is detection. A passport MRZ always starts with P<, but ID cards and travel documents use I<, A<, or C<. Our detection regex handles all of them:

function isMRZ(text) {
  const mrzPattern = /[PIAC][A-Z<][A-Z]{3}[A-Z0-9<]+/;
  return mrzPattern.test(text);
}

The pattern reads as: a document type character (P, I, A, or C), followed by a second type character or filler (<), then a three-letter country code, then the remaining MRZ characters.

3. Format Routing by Length

Once we detect and extract the MRZ string, we strip whitespace and determine the format purely by character count. This is reliable because the three lengths (90, 88, 72) don't overlap:

function parseMrz(mrz) {
  if (mrz.length === 90) return parseTD1(mrz);
  else if (mrz.length === 72) return parseTD2(mrz);
  else if (mrz.length === 88) { /* TD3 parsing */ }
}

4. Format-Specific Parsing

Each format has its own parser because the field positions differ significantly.

TD1 splits the 90-character string into three lines of 30:

const line1 = mrz.slice(0, 30);   // doc type, country, doc number, optional data
const line2 = mrz.slice(30, 60);  // DOB, gender, expiry, nationality, optional data
const line3 = mrz.slice(60, 90);  // full name (SURNAME<<GIVEN<NAMES)

TD2 splits into two lines of 36:

const line1 = mrz.slice(0, 36);   // doc type, country, name
const line2 = mrz.slice(36, 72);  // doc number, nationality, DOB, gender, expiry

TD3 splits into two lines of 44 the widest format with the most breathing room for long names.

5. Check Digit Validation

Every MRZ format includes check digits to catch OCR errors and tampering. The algorithm is the same across all formats a weighted sum using the repeating pattern 7, 3, 1:

function calculateCheckDigit(input) {
  const weights = [7, 3, 1];
  let sum = 0;
  for (let i = 0; i < input.length; i++) {
    const ch = input[i];
    let value;
    if (ch >= '0' && ch <= '9') value = ch.charCodeAt(0) - '0'.charCodeAt(0);
    else if (ch >= 'A' && ch <= 'Z') value = ch.charCodeAt(0) - 'A'.charCodeAt(0) + 10;
    else value = 0;
    sum += value * weights[i % 3];
  }
  return sum % 10;
}

What differs across formats is which fields are validated and where the check digits sit:

Check	TD1	TD2	TD3
Document number	line1[14]	line2[9]	line2[9]
Date of birth	line2[6]	line2[19]	line2[19]
Expiration date	line2[14]	line2[27]	line2[27]
Personal number	-	-	line2[42]
Composite	line2[29]	line2[35]	line2[43]

The composite check digit is the most interesting it's calculated over a concatenation of multiple fields, acting as an overall integrity check. For TD1, this spans data from both line 1 and line 2. For TD2 and TD3, it covers selected ranges within line 2.

If any check digit fails, the reader displays a warning specifying which fields failed validation, signaling a likely OCR misread.

6. Visual Feedback

To help users position documents correctly, we draw bounding boxes around recognized text regions on the canvas overlay:

function drawBoundingBoxes(words) {
  context.strokeStyle = 'red';
  context.lineWidth = 2;
  words.forEach((word) => {
    const { bbox } = word;
    context.strokeRect(bbox.x0, bbox.y0, bbox.x1 - bbox.x0, bbox.y1 - bbox.y0);
  });
}

Privacy by Design

A critical design decision was keeping everything client-side. The document image and extracted data never leave the user's browser. The entire OCR process runs locally via WebAssembly:

No server uploads
No API calls with personal data
No data retention

This makes the solution suitable for privacy-sensitive environments where transmitting document data to external servers isn't acceptable.

Technical Architecture

{aspect-ratio:500/500|500|500}

Results

The reader achieves high accuracy on well-lit, properly positioned documents. Recognition takes 1-3 seconds depending on device capabilities, with SIMD-enabled browsers seeing the fastest results.

TD3 passport output:

{
  "Nationality": "UTO",
  "Surname": "ERIKSSON",
  "Given Names": "ANNA MARIA",
  "Passport Number": "L898902C3",
  "Issuing Country": "UTO",
  "Date of Birth": "740812",
  "Gender": "Female",
  "Expiration Date": "120415",
  "Personal Number": "ZE184226B",
  "Validation": { "isValid": true }
}

TD1 ID card output:

{
  "Document Type": "I",
  "Nationality": "UTO",
  "Surname": "ERIKSSON",
  "Given Names": "ANNA MARIA",
  "Document Number": "D23145890",
  "Issuing Country": "UTO",
  "Date of Birth": "740812",
  "Gender": "Female",
  "Expiration Date": "120415",
  "Optional Data 1": "",
  "Optional Data 2": "",
  "Validation": { "isValid": true }
}

TD2 travel document output:

{
  "Document Type": "I",
  "Nationality": "UTO",
  "Surname": "ERIKSSON",
  "Given Names": "ANNA MARIA",
  "Document Number": "D23145890",
  "Issuing Country": "UTO",
  "Date of Birth": "740812",
  "Gender": "Female",
  "Expiration Date": "120415",
  "Optional Data": "",
  "Validation": { "isValid": true }
}

Lessons Learned

Custom training matters - Generic OCR models struggle with MRZ's specific character set and font. A dedicated model trained on OCR-B with only 37 character classes dramatically outperforms general-purpose text recognition.
WebAssembly is production-ready - Running Tesseract in the browser via WASM provides near-native performance with zero server infrastructure.
Camera quality varies wildly - Desktop webcams, phone cameras, and tablets all produce different results. Good lighting and a steady hand are more important than resolution.
The MRZ spec is well-designed - Check digits, fixed positions, and a limited character set make parsing reliable once OCR accuracy is high enough. The composite check digit is particularly clever - it catches errors that individual field checks might miss.
Format detection by length just works - Since TD1 (90), TD2 (72), and TD3 (88) have distinct character counts, a simple length check after stripping whitespace is a reliable and foolproof way to route parsing.
Field layout differences matter - TD1 puts the name on its own line while TD2 and TD3 pack it into line 1 alongside other data. TD1 spreads data across three lines while the others use two. These structural differences require dedicated parsers rather than a one-size-fits-all approach.

Try It Yourself

Direct try: https://eringen.com/workbench/web-mrz-reader/^

The project is open source and runs in any modern browser. Clone the repository, serve the files over HTTPS (or localhost), and point your camera at a passport or ID card. All processing happens on your device your data stays with you.

GitHub: https://github.com/eringen/web-mrz-reader^

This project demonstrates how modern web technologies can deliver functionality that once required specialized hardware, all while respecting user privacy.

DEV Community: İlhan Neğiş

Built a Free Analytics Platform, Here's Why

The Problem That Bugged Me

What Nanolytica Does

Why It's Free

It's Also Open Source

Who I Built This For

talkDOM: A Tiny Message-Passing Runtime for the DOM

The Core Idea

Message Pipelines

Receivers

Fetching and Updating Content

Server-Triggered Actions

Polling

Navigation and History

Persistence

Events

Why Build This?

Design Goals

What This Is (and Isn’t)

Closing Thoughts

SSH Gaming: Turning a Login into a Level

The Experiment

How it Works

The Stack

Why?

Building a Pure Go WebP Encoder with Claude Code

Why?

The Architecture

Where Things Got Interesting: The Bug Hunt

Bug 1: The Missing Bit

Bug 2: The Undercomplete Huffman Tree

Bug 3: The Spatial Distance Table

Working with Claude Code

The Numbers

Takeaways

Barcode Scanning on iOS: The Missing Web API and a WebAssembly Solution

The Problem

The Usual Workarounds

A WebAssembly Approach

From Prototype to Production

TypeScript + Vite

Animated CSS Overlay

The BarcodeScanner Class

Rotation Based Skew Correction

A WASM Memory Pitfall

Video Resolution Scaling

Debug Preview Panel

Results

What's Supported

Takeaway

Usage as npm Package

Browser Based Passport MRZ Reader with Tesseract.js

Why

What

TD3 Passports

TD1 ID Cards

TD2 Travel Documents

Comparing the Three Formats

The Challenge

Our Approach

1. Tesseract.js with Custom Training

2. Multi-Format Detection

3. Format Routing by Length

4. Format-Specific Parsing

5. Check Digit Validation

6. Visual Feedback

Privacy by Design

Technical Architecture

Results

Lessons Learned

Try It Yourself

The `BarcodeScanner` Class