QMK Nexus

A visual firmware builder for custom QMK keyboards.

QMK Nexus brings keyboard layout, matrix wiring, keymaps, hardware features, and firmware builds into one browser-based workflow.

Open App View GitHub Send Feedback

What it solves

Building custom QMK firmware often means moving between layout tools, wiring diagrams, keymap editors, config files, and terminal builds.

QMK Nexus brings that workflow into one visual interface so builders can design, configure, and generate firmware without hand-editing QMK source files.

QMK Nexus keyboard layout editor
1. Design the keyboard layout
QMK Nexus keymap editor
2. Map keys and features
QMK Nexus firmware build screen
3. Build and download firmware

Who this is for

  • People building hand-wired or custom QMK keyboards
  • People adapting existing QMK-supported keyboards
  • Builders who want visual tools instead of editing config files by hand
  • Developers interested in firmware tooling, visual editors, and build pipelines

What it does

QMK Nexus is a browser-based firmware builder for custom QMK keyboards. It helps users design layouts, wire matrix rows and columns, assign keymaps, configure hardware features, and build firmware from one visual workflow.

The workflow follows the way builders think about a keyboard: layout and wiring first, keymap and layers next, features and firmware build last. The backend stores user keyboards, checks build readiness, generates QMK-compatible source files, and runs builds in an isolated builder.

Workflow covered

  1. Layout and wiring - place keys, set sizes and rotations, assign matrix rows and columns, and model peripherals.
  2. Keymap and layers - edit layers, encoders, combos, tap dance, mouse keys, and QMK keycodes.
  3. Features and build - choose MCU, bootloader, OLED, encoder, trackball, RGB, split options, then generate source and download firmware.

Technical highlights / stack

Frontend
React TypeScript Vite React Konva Zustand
Backend
FastAPI Pydantic SQLite Mangum
Infrastructure
AWS Lambda S3 CloudFront ECS Fargate
Build system
Podman QMK

Why it matters

This is the kind of product work I like: take a workflow with real technical depth, respect the underlying system, then make the happy path understandable without hiding the important constraints. The same pattern applies to internal tools, hardware operations, data-heavy business apps, and developer platforms.

Technical notes

Matrix modeling The visual editor has to preserve the difference between key geometry, electrical wiring, and generated firmware macros.
Hardware features OLED, encoders, pointing devices, split boards, RGB, combos, and tap dance all need explicit UI state and backend validation.
Code generation Source generation emits QMK files for config headers, rules, keymaps, keyboard definitions, and feature-specific code.
Build isolation Firmware builds run outside the request handler in a local Podman builder or ECS Fargate build service.

Hard parts

  • Translating a visual keyboard layout into valid QMK matrix definitions, keymap files, config headers, rules files, and layout macros.
  • Keeping frontend camelCase models and backend Python models synchronized without leaking serialization details into every API endpoint.
  • Building a layout editor that supports key placement, selection, resizing, rotation, matrix assignment, and peripheral placement while staying predictable.
  • Running firmware builds safely from a web request by isolating QMK compilation inside a short-lived builder container or build proxy.
  • Supporting QMK-native imports alongside generated keyboards without promising unsupported MCU and feature combinations.

Engineering takeaways

  • Firmware generators need snapshot tests. Small formatting or macro changes can silently break generated C even when the web workflow still looks correct.
  • Visual editors need a strict data model. It is easier to render from normalized keyboard data than to infer firmware structure from canvas state after the fact.
  • Build status should be treated as durable application state, not a process-local dictionary, once builds may outlive a single backend worker.
  • Feature support should be explicit in both the UI and backend validation so the build button cannot become the first place a user discovers an unsupported target.

Current scope

Works now

  • Google sign-in and saved keyboards
  • Visual layout editor
  • Matrix wiring canvas
  • Keymap editor with layers
  • Firmware build log and download
  • Import from QMK keyboard index

Supported features

  • Encoders
  • OLEDs
  • Trackballs / pointing devices
  • RGB Matrix / RGB Light
  • Split keyboards
  • Tap Dance
  • Combos
  • Mouse Keys
  • NKRO

Still improving

  • Browser shortcut conflicts
  • Build target validation
  • Keyboard preset coverage
  • Documentation and onboarding

Related work

DBFirstDataGrid Turns database metadata into UI instead of repeating boilerplate by hand. AI Agents Local orchestration and durable memory for multi-step technical work. AutoRejection Industrial hardware/software workflow with sensors, timing, and operational constraints. PersonalSite The site architecture, deployment path, and portfolio system behind this case study.

What to do next

Try the app, review the source, or open an issue if you are building a keyboard and want to report a workflow gap. If you are evaluating the project technically, the page above shows the product flow, data modeling, firmware generation, and build pipeline behind it.

Open App View GitHub Send Feedback