vibecodeit

Build QR Tiger

YESreplaces $7/mosaves $84/yrback to the verdict

0%0 of 23 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

A QR code generator you host: live preview, colours, dot styles and a centre logo, PNG and SVG export, plus dynamic codes on your own domain that redirect through /r/:slug so a printed code can be repointed later, with per-code scan counts. The domain is the one thing you must keep forever.

estimated effort one sittingthe files for this build are in the project pack

Renderingqr-code-styling 1.5.x, vendoredRuntimeNode 22, node:http and node:sqliteDatabaseSQLiteHostingA VPS behind Caddy on a domain you will keep

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

  1. installfree

    Why Everything in this build runs on it: the server, the scripts, the tests.

    Get it Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. open ↗

    Verify node --version prints v22 or higher

  2. installfree

    Why Every step below is a command you type or a file you edit.

    Get it VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. open ↗

    Verify You can open a folder and run a command in its terminal

  3. installfree

    Why History for your code, and the way most hosts deploy.

    Get it Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. open ↗

    Verify git --version prints a version

  4. installfree

    Why Every check in Phases 1 to 3 is scanning the code with a real camera. Emulators do not count.

    Get it Any modern phone; the stock camera app scans QR codes.

  5. have readyfree

    Why Phase 3 tests the centre-logo feature; a real logo shows whether it still scans.

    Get it Your logo as PNG or SVG, at least 256x256, ideally with transparent background.

  6. roughly $10 a year

    Why Dynamic codes redirect through your domain. If the domain lapses, every printed code becomes dead paper. Do not use a domain you might drop.

    Get it Register a short one at Porkbun or Cloudflare Registrar and turn on auto-renew. A subdomain of a domain you already keep is fine. open ↗

  7. about $5 a month

    Why This needs one process running all the time with a public address.

    Get it Hetzner Cloud (from about 4 EUR), DigitalOcean or Fly.io. Ubuntu 24.04, the smallest size. You need SSH access and a public IP. Only needed for the deploy phase; develop locally first. open ↗

  8. installfree

    Why Automatic HTTPS in front of the Node process. Without TLS the browser features this relies on (and your visitors' trust) do not work.

    Get it On the VPS: follow the install steps at caddyserver.com/docs/install for Ubuntu. One Caddyfile with your domain and a reverse_proxy line is the whole config. open ↗

    Verify caddy version prints a version on the server

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- `codes`: id, slug (short, unambiguous alphabet, CSPRNG-generated), target_url,
  label, created_at, updated_at, active (bool)
- `scans`: id, code_id, scanned_at, referer, user_agent_class, ip_hash

Store a coarse user-agent bucket and a salted IP hash, never the raw values.
A `slug` is permanent: rewriting a slug invalidates every printed code that uses
it, which is the one unrecoverable mistake this tool can make.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

VariableNeededExampleWhere the value comes from
PORTrequired3000Any free port; Caddy proxies to it.
DATABASE_PATHrequired./data/qr.dbSQLite file for codes and scans.
SITE_URLrequiredhttps://go.yourdomain.comPublic base of the redirect domain. Baked into every dynamic code.
FALLBACK_URLrequiredhttps://yourdomain.com/this-code-is-inactiveWhere a deactivated or unknown code lands. A dead printed code should explain itself.
IP_SALTsecretrequiredhex-from-openssl-randopenssl rand -hex 32, once. For hashing scanner IPs.
ADMIN_USERrequiredadminAny username for the basic-auth admin pages.
ADMIN_PASSsecretrequiredchange-me-to-a-long-random-stringGenerate one: openssl rand -base64 24. Never reuse a real password.

The build, in order

  1. Static generator

    Type text, see a code, scan it.

    1. Install the pinned version and copy its browser bundle into public/vendor so nothing loads from a CDN at runtime.

      Files public/index.htmlpublic/app.js

      terminal
      mkdir qr && cd qr && git init && npm init -y && npm pkg set type=module
npm install qr-code-styling@1.5.0
mkdir -p public/vendor data && cp node_modules/qr-code-styling/lib/qr-code-styling.js public/vendor/

    2. new QRCodeStyling({ width: 300, height: 300, type: 'canvas', data }) then .append(container). Re-render on input with a 150 ms debounce.

    done when · tick each as it passes
    next phase

  2. Customization

    Colours and styles that update live, with a warning when the result would not scan.

    1. dotsOptions.color and type (square, rounded, classy), cornersSquareOptions, backgroundOptions.color, margin. Every control re-renders immediately; no Apply button.

    2. Compute the contrast ratio between foreground and background; below roughly 3:1 show a warning while still rendering. A beautiful unscannable code is the failure users ship.

    done when · tick each as it passes
    next phase

  3. Centre logo

    A logo in the middle that does not break scanning.

    1. imageSize around 0.3, margin, hideBackgroundDots true. Read the file locally with FileReader; nothing is uploaded.

    2. qrOptions.errorCorrectionLevel = 'H' with a logo, back to M without. Cap the logo at roughly a quarter of the code.

    done when · tick each as it passes
    next phase

  4. Export

    PNG and SVG that reopen correctly, and copy to clipboard that works in Safari too.

    1. download({ name, extension: 'png' | 'svg' }) at 512, 1024 or 2048 by re-instantiating at that size.

    2. Always pass a Promise resolving to a Blob into ClipboardItem: Safari requires the promise form and Chromium accepts it, so one code path works everywhere. Call navigator.clipboard.write inside the click handler or the user gesture is lost.

    done when · tick each as it passes
    next phase

  5. Dynamic codes

    Codes that point at /r/:slug so the target can change after printing.

    1. codes (id, slug unique, target_url, label, created_at, updated_at, active). Slugs 6+ characters from an alphabet without 0/O/1/l/I, CSPRNG-generated, or custom.

      Files server.mjs

    2. 302 to target_url. Unknown or inactive slugs redirect to FALLBACK_URL rather than 404ing.

    3. Editing a target must never change the slug. Deactivating keeps the row. Each row shows its code image and a download button.

    done when · tick each as it passes
    watch out
    • A slug is permanent. Rewriting one invalidates every printed code that uses it, which is the one unrecoverable mistake this tool can make.
    next phase

  6. Scan analytics

    Counts you can explain, written after the redirect.

    1. scans (id, code_id, scanned_at, referer, user_agent_class, ip_hash). Never before the 302.

    2. Link scanners and chat previewers inflate counts otherwise.

    done when · tick each as it passes
    next phase

  7. Deploy

    Live on the domain you will keep, backed up, documented.

    1. Files deploy/qr.serviceCaddyfile

    2. README: the domain-is-forever warning stated once plainly, which error-correction level is used and why it changes with a logo, and when to use static instead of dynamic.

      Files README.md

    done when · tick each as it passes
    next phase
what this build does not replace
after v1, if you want it

Need the files? The project pack on the verdict page hands your agent the whole brief · more qr codes.