Open-source project
zhengkyl/qrframe avatar
zhengkyl/qrframe

qrframe hands presets an unsanitised renderer and a bit-flag matrix, and warns its output may not scan

code-based qr code designer

3,374 stars111 forksTypeScriptMIT

At a glance

What is it?
A browser-based QR code designer where the data layer is a spec-compliant encoder and the appearance layer is arbitrary code you write in the browser. The technical core is the matrix handed to a preset: every module is a byte of bit flags saying whether it is data, finder, timing, format or modifier, which is what lets a renderer restyle the picture without touching the structure. The project's own caution is that its decorative examples may not be reliably scannable, and nothing in the toolchain checks.
Who is it for?
qrframe suits someone who needs a QR code to look like a designed object rather than a grid of squares, and who is comfortable writing a renderer function. Check four things first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 46 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • zhengkyl/qrframe3,374 ★ · -1
Star history
Repository2026-09-242026-11-15
zhengkyl/qrframe3.4k3.4k

-1 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The project says its own examples may not be scannable

The most important sentence in this readme is a callout placed above the gallery, and it is a warning rather than a feature.

The example QR codes may not be reliably scannable, and results may vary drastically based on device and scanner. Underneath it, a second line makes the intent explicit: this project is a tool to create designs, and the examples are only examples.

That reframes everything else in the repository. A conventional QR encoder's job is that a scanner reads the code back, and every design decision there is subordinate to that. This project separates the two halves and lets you take the appearance half as far as you like, so the guarantee a reader might assume from seeing a QR shape has been explicitly withdrawn by the author.

The gallery is organised to make that point structurally. Its four section headers are Creative possibilities, Import external libs and fetch external files and similar, Styles copied from a named inspiration, and Boring options are available. The last category is listed as a first-class option rather than a fallback, which tells you the author expects a meaningful share of readers to want exactly that.

Worth pairing with the caution: nothing in the toolchain verifies scannability. The package has four scripts and none of them tests anything, so there is no automated check that a given preset still produces a readable code.

For any use where a failed scan means a failed payment, a failed login or a failed ticket, the boring preset is the correct choice and the artistic ones are not candidates.

Two layers, and only one of them is allowed to be creative

The feature split is short and it maps exactly onto the QR specification's own structure.

The data layer is four things: encoder, version, error tolerance and mask pattern. That is the whole of what determines what the code says and how it is laid out at the module level, and those four are described as powered by a separate package, `furious-qr`, which the readme calls the author's own small and hackable QR code generator. So the specification-compliant half of the system lives in a different package, and this repository consumes it.

The appearance layer is where the freedom is. You can choose any preset, customise one, or create a new one from scratch in a code editor, and you define arbitrary UI parameters in code rather than through a fixed settings panel.

That arrangement has a consequence worth naming. Because appearance is code rather than configuration, there is no fixed set of style options, which is why the boring designs are examples rather than presets and why the gallery's categories are open-ended. The design space is whatever a renderer function can draw.

It also means the tool has no opinion about output format at the library level. A preset chooses between producing an SVG string and drawing onto a canvas, and the readme points at a blog post by the author for a deeper account of how QR codes work and how to make them look good. The code is the intended interface, not a settings screen.

Every module is a byte of bit flags, so a renderer knows what each one is for

This is the detail that makes the whole design possible, and it is easy to skim past.

A preset receives a `qr` object with four fields. `matrix` is a `Uint8Array`. `version` runs from 1 to 40. `mask` runs from 0 to 7. `ecl` runs from 0 to 3, corresponding to Low, Medium, Quartile and High error correction.

The matrix itself is described as a square where one side is `version * 4 + 17` wide, with modules stored left to right and then top to bottom. That formula is the specification's own dimension rule, and it means the array length is fully determined by the version: 21 modules for version 1, 177 for version 40.

The important part is what sits in each byte. The matrix is not a grid of zero and one values. Each element is a set of bit flags describing the module's role:

ts
const Module = {
  ON: 1 << 0,
  DATA: 1 << 1,
  FINDER: 1 << 2,
  ALIGNMENT: 1 << 3,
  TIMING: 1 << 4,
  FORMAT: 1 << 5,
  VERSION: 1 << 6,
  MODIFIER: 1 << 7,
};

All eight bits of a byte are used, which is why version, mask and error correction are carried alongside the matrix rather than inside it. A renderer can therefore distinguish a data module from a finder pattern, an alignment pattern, a timing pattern, a format area or a version area, and the `MODIFIER` flag is set for finder and alignment centres and for the format and version copies.

That is the whole trick. A preset can restyle every payload module and leave the structural ones alone, which is exactly the boundary a scanner cares about. The information needed to make that decision is handed to the renderer rather than being thrown away after encoding.

One schema declaration generates both the controls and the params object

A preset must export `paramsSchema`, and either `renderSVG` or `renderCanvas`. The schema is what defines the user interface, and it doubles as the contract for the values passed to the renderer.

The mechanism is that the schema's keys become the keys of a `params` object, each paired with the value from its respective input component. One declaration therefore produces the form controls and the argument object at the same time, and there is no separate signature to keep in sync.

The coupling has a practical edge. Since the keys are shared, renaming a schema entry renames the corresponding property in `params`, so a preset and its UI cannot drift apart, but a preset author has to treat the schema keys as public API.

Six control types appear in the worked example. A number takes a minimum, a maximum, a step and a default. A boolean takes a default. A color takes a CSS colour string, given as hex, rgba or hsla. A select takes an options array and a default that is the first option. A file takes an accept list such as `.jpeg, .jpg, .png` with a null default. An array takes a `props` value describing its element.

Validation is deliberately thin. All properties besides `type` are optional, with exactly two exceptions: a `select` must have a nonempty options array, and an `array` must have a valid `props` value. The `array` element accepts any type except `array`, so nesting is excluded by design rather than left to fail. The example block for the array case stops partway through its `props` object, after the type and a comment.

The colour type lines up with a dependency: `@melloware/coloris` is a colour picker, which is what a `color` control needs to be usable.

Preset code runs in a worker with a five second timeout and no output sanitisation

The security posture is stated in three bullets, and they are unusually blunt.

All preset code runs in the browser in a web worker with no restrictions. There is a five second timeout to stop infinite loops. Generated SVGs are not sanitised. And then the conclusion: there is nothing to exploit or attack, and no risk from bad code except crashing your tab.

That is a stated threat model rather than an oversight, and the reasoning holds together. A renderer receives the QR matrix and a params object and returns markup. It has no credentials, no server access and no data the page does not already hold, so the worst outcome of a hostile preset is a worker that spins until the timeout kills it or a document that renders markup you did not intend to accept. The five second timeout exists for the first case, and the second is accepted rather than mitigated.

The consequence is that the unsanitised SVG reaches the document. If you install third-party presets, you are trusting them the way you would trust a script tag, and the project's own wording is the clearest statement of that.

Running in a worker is also what makes canvas rendering possible without freezing the interface. The canvas signature takes an `OffscreenCanvas`, which is the worker-side canvas type, so a preset that draws can do its work off the main thread with the same five second ceiling applying.

A preset is two exports, and the choice is string or canvas

The whole authoring contract is two exports and one of two render targets:

ts
type renderSVG = (qr: Qr, params: Params) => string;

type renderCanvas = (qr: Qr, params: Params, canvas: OffscreenCanvas) => void;

The two have different shapes on purpose. Returning an SVG string keeps the output inspectable, diffable and stylable, which matters when you want to post-process the file or check what a preset drew. Drawing onto a canvas returns nothing and gives you the full 2D API, which is what you want for effects that are awkward to express as vector output, such as per-pixel work over a rasterised image.

Both receive the same first two arguments, so the choice of target does not change how you read the params or the matrix.

The examples in the repository lean on both. Of the twenty-two files under `examples/`, the majority are `.svg` while seven are `.png`, and the boring designs are among the raster ones. That split is consistent with the two render targets being genuinely used rather than one existing as a fallback.

There is no third option offered. No PDF, no raster export at a chosen resolution, no batch generation over many codes, and no headless render path are described, so anything beyond producing one design in the browser is outside what the preset contract supports.

Serving under a nonroot path is broken until an upstream pull request ships

The self-hosting section is three lines, and one of them is a blocker.

The build is `pnpm run build`, and the static files end up in `.output/public`. Then: serving under a nonroot path is broken until a specific pull request against SolidStart is merged and released. Once that has happened, update `@solidjs/vite-plugin-nitro-2` and modify `base` in `vite.config.ts`.

The condition is unusually precise. It names the upstream repository, the change that has to land, the package to update afterwards, and the configuration key to set. That is what a known-broken deployment note should look like, and it is more useful than a general warning would be.

It matters more than usual here because of what it implies about the framework underneath. `@solidjs/start` is pinned to exactly `2.0.0-alpha.3`, an alpha with no range, and the vite plugin sits at `^0.1.0`. A tool built on a framework alpha inherits that alpha's churn, and this deployment limitation is one visible consequence.

The node floor is declared separately as `>=18`. So the stated requirement is Node 18 or newer, the framework is a 2.0.0 alpha, and the bundler is Vite on the 8 line. Those four facts together describe the support surface better than any compatibility statement would.

For self-hosting, the practical reading is: a root-path deployment is the supported configuration today, and a subpath deployment needs you to wait for a specific upstream release.

Four scripts, no test, and the editor has Vim keybindings

The package manifest is small enough to read as a description of the project. The name is `qrframe`, the module type is ESM, and there is no version field anywhere in it.

There are four scripts: `dev`, `build` and `start` are all Vite, and `fmt` runs `oxfmt`, which is the only development dependency besides a UnoCSS transformer. There is no test script, no lint script and no typecheck script. For a tool whose stated failure mode is that its output may not scan, that is the most consequential omission in the manifest.

The editor is CodeMirror 6, assembled from individual packages rather than the umbrella alone: commands, the JavaScript language mode, the language core, state, the one dark theme and the view component, plus `codemirror` itself. `@replit/codemirror-vim` is also a dependency, which means the preset editor supports Vim keybindings. That is a deliberate choice for a tool whose users write code, and it is not a default.

Around that sit `@kobalte/core` for unstyled components, `lucide-solid` for icons, `@thisbeyond/solid-dnd` for drag and drop, `@solidjs/router` for routing, and UnoCSS three times over: the main package, its reset, and a variant-group transformer as a development dependency, with `uno.config.ts` at the top level.

There is also no release history. The repository has no GitHub releases, and the manifest carries no version, so there is nothing to pin. Attribution is explicit where it matters: the project is described as blatantly inspired by two named projects, and one gallery category is labelled as styles copied from one of them.

Editorial conclusion

qrframe suits someone who needs a QR code to look like a designed object rather than a grid of squares, and who is comfortable writing a renderer function. Check four things first. Whether your QR code has to be reliably scannable, because the project says outright that its examples may not be and that results vary by device and scanner, and the package has no test script that could tell you otherwise. Whether you need decorative output at all for the use, since for identity or payment a plain code is the correct choice. How you host it, because serving under a nonroot path is stated to be broken until a specific upstream SolidStart change ships. And what you are importing, because `@solidjs/start` is pinned to a 2.0.0 alpha while the vite plugin sits on a 0.1 line. If you write the renderer yourself, the bit-flag matrix tells you which modules are structural and which are payload, which is the information you need.

Frequently asked questions

What is qrframe?

A browser-based, code-based QR code designer built on SolidStart. The data layer exposes encoder, version, error tolerance and mask pattern and is powered by the author's own `furious-qr` package; the appearance layer is a preset written as code, either customised from an existing one or created from scratch in a CodeMirror editor. It is MIT licensed with no GitHub releases and no version field in its package manifest.

Do qrframe's example QR codes actually scan?

The project says not to rely on it. A caution above the gallery states the example QR codes may not be reliably scannable and that results vary drastically by device and scanner, and adds that the project is a tool to create designs and the examples are only examples. The package has no test script, so nothing in the toolchain verifies scannability either.

How do I write a qrframe preset?

Export `paramsSchema` plus either `renderSVG` or `renderCanvas`. The schema defines the UI controls and supplies the keys of the `params` object. `renderSVG` takes `(qr, params)` and returns a string, while `renderCanvas` takes `(qr, params, canvas)` with an `OffscreenCanvas` and returns nothing. All schema properties besides `type` are optional, except that a `select` needs a nonempty options array and an `array` needs a valid `props`.

What does the qr object give a qrframe preset?

Four fields: `matrix` as a `Uint8Array`, `version` from 1 to 40, `mask` from 0 to 7, and `ecl` from 0 to 3 for Low, Medium, Quartile and High. The matrix is a square one side of `version * 4 + 17` modules wide, stored left to right then top to bottom, and each byte carries bit flags for ON, DATA, FINDER, ALIGNMENT, TIMING, FORMAT, VERSION and MODIFIER, with MODIFIER set on finder and alignment centres and the format and version copies.

Can I self-host qrframe under a subpath?

Not yet. The readme states that serving under a nonroot path is broken until a named SolidStart pull request is merged and released, and that the remedy afterwards is to update `@solidjs/vite-plugin-nitro-2` and set `base` in `vite.config.ts`. The build is `pnpm run build` with static output in `.output/public`.

Official sources

  1. Issues
  2. License: MIT
  3. Project website
  4. README
  5. zhengkyl/qrframe on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/zhengkyl-qrframe.svg)](https://hysenlabs.com/projects/zhengkyl-qrframe)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/zhengkyl-qrframe.svg)](https://hysenlabs.com/projects/zhengkyl-qrframe)

Was this useful?