QRCraftly
qrcraftly.com is a free QR code studio that runs entirely in your browser. It makes styled, scannable QR codes for links, Wi-Fi, contacts, payments and more; scans and checks existing codes; and sends files between devices as an animated stream of QR codes, with no network. Nothing you type or upload leaves your device.
Contents
The QRCraftly Pledge
QRCraftly is not ad supported, and it never will be. No ads, no tracking, no sign-up, and everything runs in your browser. If it ever comes down to ads or nothing, the project will be shut down before a single ad goes on it; the only way it would change hands is an outright purchase of the whole project.
Read the full pledge, and exactly what is and isn't collected, in docs/PLEDGE.md or at qrcraftly.com/free-forever.
Features
Generator
- Content types: URLs, plain text, Wi-Fi networks (WPA, WEP, EAP or open), email, vCard contacts, phone numbers, SMS, cryptocurrency payments, calendar events, GPS locations, video meetings (Zoom, Microsoft Teams, Google Meet) and social profiles (Instagram, X, TikTok). Each type has its own page, such as
/wifi-qr-code.
- Bulk CSV: turn a spreadsheet of up to 500 rows into a ZIP of codes (
/bulk-csv-qr-code). Every row goes through the same payload checks as a single code.
- Patterns: Standard Industrial, Modern Soft, Swiss Dot, Fluid Ink, Cyber Circuit, The Hive, Grunge and Starburst.
- Colours: foreground, background and finder-pattern colours, with contrast-checked presets and a "Low Contrast" warning.
- Logos: embed a logo with padding and a square, circle or no border. Supported custom logo formats are image/jpeg, image/png, image/webp, image/svg+xml. Maximum file size is 2MB. Maximum logo size is 30% of the code, so it still scans.
- Mosaic QR: tile a picture across the whole code. Each module takes the image's colour while keeping its dark or light value, so the code still scans (Halftone or Tiles, with adjustable Scan Contrast; ADR 0019).
- Live scannability: a worker re-checks contrast and decodes the code as you edit, and warns before you export a code that may not scan.
- In the wild: preview the code on a poster, business card, table tent, phone screen or sticker, all drawn in code. Set a printed width to see module size and estimated scan distance, and run a viewing test (distance, glare, dim light, tilt).
- Style tools: a gallery of every pattern and preset drawn on your own code, "Surprise me", up to 50 steps of undo and redo in memory, and a command palette (
Ctrl/Cmd+K) with keyboard shortcuts (? lists them).
- Style files and templates: save a look as a
.qrcraftly.json file, or as a brand template in the browser. Both hold colours and layout only, never your content or images.
- Export: PNG, JPEG, WebP, or vector SVG, EPS and PDF, with native "Save As" where the browser supports it and the Web Share API on mobile.
- Phone wallet: "Add to phone wallet" makes a plain wallet card image for Google Wallet's photo import or the iPhone Photos app. People with their own Apple or Google issuer keys can build and sign a pass in the tab; the keys stay in memory ().
Scanner and checker
- Scan to fill: scan a code with the camera or from an image file and load it into the matching form.
- Scanner (
/qr-code-scanner) and checker (/qr-code-checker): decode a code on your device and explain what it does before you act on it. Links show their real host and are checked offline for disguises such as look-alike domains; dialer codes, texts to short numbers, Wi-Fi without a password and wallet checksums are called out. Only http and https links can be opened from the result. See ABUSE_PROTECTIONS.md.
- The decoder is our own Rust module,
crates/qr-decode, compiled to WebAssembly and run in a worker (ADR 0036).
Air-Gapped File Transfer (beta)
- Send a file or folder from one device's screen (
/file-transfer) to another device's camera (/file-transfer/receive) as an animated stream of QR codes. No network, Bluetooth or USB is involved.
- The sender picks Steady, Balanced or Fast and sees the time for the file before it starts. The receiver can join at any point, watches the file assemble, and finishes with a verified summary and Open, Save and Receive-another actions.
- Private transfers encrypt the file with AES-256-GCM. The key never appears in the stream: it is shown as eight words or a separate key QR (ADR 0025). Received file names are sanitised, risky types need confirmation, and receives are capped at 100 MiB.
- Several faster modes are previews behind switches under Advanced: a new outer code, several codes per frame, and a webcam back channel that lets the receiver steer the speed. A wallet-compatible BC-UR mode is also available. Speeds come from simulation only until the device checklist has real results.
- The design, its status and its evidence rules are in docs/optical-transfer.
QR Arcade
Damage a QR design and watch whether a real decoder still reads it (/arcade). It shows how error correction works.
Everywhere
- Works offline after one visit: a service worker caches the homepage generator, with its encoder and workers, on the first visit, and other pages as you open them.
- Accessible: keyboard navigation, screen-reader labels, visible focus and WCAG contrast checks, tested with axe in unit and end-to-end tests.
- Light and dark themes, a layout that works from phones to desktops, and reduced-motion support.
Privacy and security model
| Promise | How it is kept |
|---|
| Your content stays on device | Generation, scanning, export and file transfer run in the browser. Content is never sent over the network or put in a URL query string. There is no server code, API or database (ADR 0022). |
| Static codes only | Every code holds its content directly, so it keeps working without QRCraftly and nobody can track or switch it off. There are no redirect ("dynamic") codes. |
| Nothing is stored by surprise | Persistent browser storage is limited to an allowlist (theme preference and saved style templates), enforced by an AST audit before every build (ADR 0001). |
| No tracking | No ads, analytics, telemetry or third-party scripts (PLEDGE.md). The host still sees ordinary request logs; the privacy page says exactly what. |
| Hardened pages | A strict Content Security Policy with hashed inline scripts, a Permissions Policy, SVG and link sanitisation (SECURITY.md). |
For regulated settings, COMPLIANCE.md describes the volatile-memory guarantees and what the host can see.
Quick start
Prerequisites
- Node.js
^22.22.2 or >=24.15.0. .nvmrc pins the version CI uses.
- pnpm, at the version pinned in
package.json (packageManager). Run corepack enable once to get it. Never use npm or yarn.
- Rust only if you change something in
crates/. The built WebAssembly modules are committed in src/wasm/, so building and testing need no Rust (docs/RUST.md).
Install and run
git clone https://github.com/fderuiter/QRCraftly-web.git
cd QRCraftly-web
pnpm install
pnpm dev
The dev server runs at http://localhost:3000. pnpm install also installs the Git hooks (scripts/hooks/install.js points core.hooksPath at .githooks/). pnpm run wizard:dev walks through the local setup interactively.
Build and preview
pnpm build # pre-renders every page to static HTML in dist/, then runs the post-build security scripts
pnpm preview # serves dist/ at http://localhost:3000
Everyday commands
| Command | What it does |
|---|
pnpm dev | Starts the Vite dev server. It reloads the page on save (no Fast Refresh). |
pnpm exec vitest run | Runs the unit tests once (pnpm test watches). Add --coverage for a coverage report. |
pnpm test:e2e | Runs the Playwright end-to-end tests. Run pnpm exec playwright install once on a fresh machine. |
pnpm test:build | Runs the checks on the built site in tests/build-output/ after pnpm build; fails when there is no build. |
pnpm test:slow | Runs the slow tests (*.slow.test.ts) and the benchmarks (*.bench.ts) that the unit run leaves out. |
pnpm run lint | Runs every static check that CI runs (see Quality gates). |
pnpm run format | Formats the repository with Prettier. pnpm run format:classes sorts Tailwind classes. |
pnpm build | Builds the site, including the sitemap, social images, service worker and CSP hashes. |
pnpm run check-bundle-size | Checks the built site against the size budgets. Run it after pnpm build. |
pnpm run docs:sync | Regenerates the UI catalog entries after UI component changes. |
pnpm run docs:lint | Checks Markdown links, anchors, ADR numbering and the UI catalog. |
pnpm run wasm:build | Rebuilds the Rust modules into src/wasm/ (needs Rust). wasm:check verifies the committed builds. |
pnpm run licenses:sync | Updates the list of packages shipped to the browser, shown on /acknowledgements. |
pnpm run bench:* | Benchmarks: scanner, wasm, qr-encode, transfer, outer-code, , , and more. |
Architecture
Stack
| Layer | Choice |
|---|
| UI | React 19 and TypeScript (strict) |
| Routing | Vike, with every page pre-rendered to static HTML at build time; page scripts start after first paint (ADR 0034, ADR 0035) |
| Build | Vite 6 |
| Styling | Tailwind CSS v4, CSS-first: tokens and the dark variant live in src/layouts/index.css (@theme, @variant); there is no tailwind.config.js (STYLE_GUIDE.md) |
| Compute | Our own Rust compiled to WebAssembly, with no third-party crates (ADR 0033, RUST.md) |
| Concurrency | Web Workers for scannability, matrix and maze building, scanning and decoding, passing pixels as transferable ArrayBuffers (SCALING.md) |
| Hosting | Cloudflare Workers with Static Assets only, no server code (ADR 0012) |
| Tests | Vitest with jsdom and axe-core (tests/utils/axe.ts); Playwright with axe for end-to-end tests |
Runtime dependencies are only React, React DOM, Vike, vike-react and lucide-react. Our own code comes first: a new runtime dependency needs its own ADR (ADR 0040).
Deep modules
Core features live in deep modules under src/packages/. App code imports a package only through its root entry points, and our own checker (scripts/check_boundaries.js) enforces the boundaries (ADR 0007, ADR 0052, src/packages/README.md).
| Package | Responsibility |
|---|
qr-matrix | Turns a configuration into a module matrix and draws it: patterns, eyes, logos, mosaic and mazes |
qr-payload | Builds, parses and validates the payload for every content type |
qr-export | Templates and self-contained, sanitised SVG export |
qr-decode | Our QR decoder (crates/qr-decode) |
scannability | Off-thread contrast audits, decoding checks and the scannability verdict |
optical-scanner | The Camera Session and off-thread decoding for live cameras and image files |
optical-transfer | Air-Gapped Optical Transfer: Prism frames, fountain and outer codes, sender, receiver, multi-code, feedback |
optical-modem | Experimental colour modem, off unless the build sets VITE_OPTICAL_MODEM=true |
link-safety | Offline checks for disguised links |
wallet-pass | Apple .pkpass files and Google Wallet save links, built and signed in the browser with the user's keys |
bulk-csv | The Bulk CSV generator's parsing and batching |
arcade | Game logic and damage analytics for the QR Arcade |
wasm-runtime | Loads and instantiates our WebAssembly modules |
Rust crates
| Crate | Module in src/wasm/ | What it does |
|---|
qr-encode | qr-encode.wasm | QR encoder |
qr-decode | qr-decode.wasm | QR decoder, including the tracked fast path for file transfer |
prism-fec | prism-fec.wasm | The file-transfer outer code (LT over an LDPC precode) |
modem | modem.wasm | Experimental optical modem kernels |
core | (shared) | GF(256), Reed-Solomon, CRC-32, QR tables and the module allocator |
selftest | selftest.wasm | A tiny module that proves the toolchain, build and loader work |
Project structure
.
├── AGENTS.md Invariants for contributors and AI agents
├── CLAUDE.md Claude Code memory; imports AGENTS.md
├── CONTEXT.md Domain glossary (use these terms)
├── RELEASING.md Release, deployment and rollback runbook
├── crates/ Rust sources for the WebAssembly modules
├── docs/ Design docs, ADRs, benchmarks and public guides (see the map below)
├── e2e/ Playwright end-to-end tests
├── public/ Static assets, _headers, _redirects and the web app manifest
├── scripts/ Build, audit, benchmark and release scripts
├── src/
│ ├── components/ React components; ui/ holds the shared primitives (see UI_CATALOG.md)
│ ├── data/ Page copy, navigation and landing pages
│ ├── hooks/ React hooks (download, upload, scannability, focus)
│ ├── layouts/ Layout, document head and index.css (theme tokens)
│ ├── packages/ Deep modules (see above)
│ ├── pages/ Vike routes: one folder per page
│ ├── utils/ App utilities (colour math, file names, storage of templates)
│ └── wasm/ Committed, reproducible WebAssembly builds
└── tests/ Vitest tests for scripts, tooling and cross-cutting behaviour
Quality gates
pnpm run lint runs the same static checks as CI:
- Policy audits: dependency licences and the allowlist, no third-party Rust crates, code-to-doc pairing, the storage allowlist, platform-independent paths and static SVG paths.
- Docs: links, anchors, ADR numbering and the UI catalog.
- Code: TypeScript, package-boundary checks, ESLint (including jsx-a11y and security rules), Knip for dead code, Prettier and a duplication limit.
- Design: WCAG contrast of UI colours, and a design-token ESLint rule that rejects raw palette colours and arbitrary colour or size values anywhere in
src/.
CI also runs the unit tests with coverage, the end-to-end tests, the build with its post-build security scripts (bundle AST audit, CSP hashing), a reproducibility check of the committed WebAssembly, a dependency audit and Lighthouse. Size budgets, checked by pnpm run check-bundle-size:
- The check fails if any page's first load (HTML, CSS and startup scripts, gzipped) exceeds 260 KB, or 308 KB once the Rust modules the page fetches on open are added (the generator pages fetch the QR encoder and decoder).
- It fails if React and react-dom are not in their own
vendor chunk, which stays cached across app-only releases.
- It fails if all shipped JavaScript and CSS together exceed 650 KB gzipped.
- Each Rust module has its own gzipped budget, for example 32 KB for
qr-decode and 10 KB for prism-fec.
Before every commit, our own pre-commit hook (.githooks/pre-commit) formats and lints the staged files and runs the secret, storage and docs audits, then the duplication audit, the type check and the unit tests (ADR 0044). The staged-file rules are in scripts/hooks/staged.config.js.
Contributing
- Read the guardrails. AGENTS.md holds the invariants (CLAUDE.md imports it, so Claude Code sessions load it automatically): client-side only, the storage allowlist, reuse of shared UI components, semantic design tokens, hardened workflows and in-house first. Use the vocabulary in CONTEXT.md, and check docs/adr before changing a settled decision.
- Branch from
main with a prefix: feat/, fix/, docs/, refactor/, chore/ or agent/ (a Claude session keeps the claude/ branch it is given). main is the only long-lived branch (ADR 0020).
- Reuse before you build. Check UI_CATALOG.md before adding a visual element; sliders, buttons and colour pickers have shared components, and colour maths lives in
src/packages/core/encoding.ts.
- Keep docs in step. Run
pnpm run docs:sync after changing shared UI or a public doc, and record a new architectural decision as an ADR (docs-maintenance.md).
- Check locally:
pnpm run lint and pnpm exec vitest run; add pnpm build and pnpm test:e2e when you touch the build, routing, rendering or input flows.
- Open a pull request against
main with a Conventional Commits title (, , ). The title becomes the squash commit and drives the next version. Fill in the PR template.
Dependencies: Dependabot proposes npm updates daily and GitHub Actions updates weekly, grouped to keep the noise down; security fixes come on their own. A new dev dependency or third-party Action needs a one-line reason in the PR and a row in the FOUNDRY.md scorecard. When a package that ships to the browser is added or removed, the build fails until you run pnpm run licenses:sync and check its licence.
Issues: use the GitHub issue forms for bugs and ideas. Labels follow triage-labels.md.
Releases and deployment
- Cloudflare Workers Builds deploys every push to
main to production (https://qrcraftly.com) and every other branch to a preview URL, https://<branch>-qrcraftly.fpderuiter.workers.dev. GitHub Actions never deploys; it is the quality gate, and after each merge it smoke tests production.
- Versions follow SemVer and come from the Conventional Commits on
main. pnpm run release:prepare opens a release/vX.Y.Z pull request with the version bump and CHANGELOG.md; merging it tags the release and publishes it on GitHub. A maintainer merges release pull requests by hand. Never edit the version in package.json or create tags manually.
- To roll back, restore the previous version in Cloudflare, then fix forward with a pull request.
Details are in RELEASING.md and WORKFLOWS.md.
Documentation map
Security
Please report vulnerabilities privately, as described in SECURITY.md. Do not open a public issue for a security problem.
License
AGPL-3.0-or-later. The /acknowledgements page lists the open-source packages the site ships, with their licences.
