Fork of discontinued https://github.com/nickcoutsos/keymap-editor with Forgejo integration
  • JavaScript 78%
  • Nix 10.7%
  • CSS 8.4%
  • HTML 2.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-30 07:47:50 +01:00
nix Do not set MemoryDenyWriteExecute: V8 JIT needs RWX pages 2026-10-30 07:47:50 +01:00
public Forgejo shim: fix picker/save error contract, rebrand UI to Forgejo, drop upstream help widget 2026-10-29 21:19:01 +01:00
server Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00
tools Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00
.gitignore Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00
flake.lock Bump nixpkgs pin and npm deps hash 2026-10-29 22:42:58 +01:00
flake.nix Bump nixpkgs pin and npm deps hash 2026-10-29 22:42:58 +01:00
package-lock.json Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00
package.json Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00
README.md Drop scratch/, move e2e test to tools, rename to keymap-editor, credit upstream 2026-10-29 21:22:24 +01:00

keymap-editor (Forgejo)

WYSIWYG editor for ZMK keymaps, wired to a Forgejo instance instead of GitHub. A Forgejo port of nickcoutsos/keymap-editor: the upstream frontend, unchanged apart from its API base URL, talking to a small backend written here against the Forgejo API.

The frontend is the deployed keymap-editor bundle (mirrored into public/, API base URL patched to window.location.origin) and the backend re-implements the small API surface it talks to on top of the Forgejo API. Keymap parsing, layout generation and serialization are the bundle's own modules, loaded headless in Node (tools/bundle.mjs).

Requirements

  • A Forgejo instance (tested against 16.0.6)
  • Node 22+ for local development

Run locally

npm install
FORGEJO_CLIENT_ID=... FORGEJO_CLIENT_SECRET=... PUBLIC_URL=http://localhost:3000 npm start

Open http://localhost:3000, then log in against your Forgejo instance.

Environment

Variable Default Meaning
FORGEJO_CLIENT_ID required OAuth2 client id
FORGEJO_CLIENT_SECRET required OAuth2 client secret
FORGEJO_URL https://git.notthebe.ee Forgejo base URL
PUBLIC_URL http://localhost:$PORT External URL, must match the OAuth redirect
PORT 3000 Listen port
DATA_DIR .data Session storage
KEYMAP_PATHS config Comma separated repo dirs holding *.keymap

Forgejo OAuth application

Create an OAuth2 application on your Forgejo instance (Settings → Applications → OAuth2 Applications) with:

  • Redirect URI: <PUBLIC_URL>/github/authorize/callback
  • Confidential client: yes

The editor only needs the instance-level /user, /user/repos, /repos/* and /git/* endpoints of the logged-in user, so no extra scopes are required.

Keyboard definitions

Bundled metadata for 89 keyboards ships in public/keyboard-data/: say corne in the picker and it renders. For your own board, add <KEYMAP_PATHS>/<keyboard>.json (the standard keymap-editor keyboard definition) next to the .keymap file; it takes precedence over the bundled definition.

Save behaviour

Saving serializes the edited model back into the original devicetree source with the bundle's own formatter and commits through the Forgejo contents API using the sha the editor loaded — a concurrent change aborts with commitMismatch instead of clobbering it.

NixOS deployment

{
  inputs.keymap-editor.url = "git+https://git.notthebe.ee/notthebee/keymap-editor";

  # in your host config
  imports = [ inputs.keymap-editor.nixosModules.default ];

  services.keymap-editor.enable = true;
  services.keymap-editor.publicUrl = "https://keymap.example.com";
  services.keymap-editor.environmentFile = config.age.secrets.keymap-editor.path;
}

The service listens on 127.0.0.1:3000-ish plain HTTP; put a reverse proxy in front (any nginx/caddy with websocket upgrade for /github/events). The environmentFile must define FORGEJO_CLIENT_ID and FORGEJO_CLIENT_SECRET.

Standalone:

nix run .            # needs the env vars above
nix build .#default

Checks

npm run check                  # parse → layout → serialize round trip
npm test                       # full API flow against a stubbed Forgejo
nix build .#checks.x86_64-linux.self-check

Layout

  • public/ — mirrored frontend bundle with the API base URL patched
  • server/index.mjs — HTTP API, static hosting, websocket build events
  • server/lib/{auth,forgejo,keymaps,zmk}.mjs — OAuth, Forgejo client, keymap files, bundle module bridge
  • tools/bundle.mjs — runs the mirrored webpack bundle inside node:vm
  • tools/self-check.mjs — offline round-trip check
  • nix/module.nix — NixOS module

Upstream / credits

This project is a Forgejo port of nickcoutsos/keymap-editor (MIT). The frontend bundle in public/ — editor UI, keymap parser, layout generator, devicetree serializer, keyboard metadata — is upstream's build, used unmodified apart from the API base URL and UI wording. All credit for it goes to Nick Coutsos and its contributors; that project is the place to report editor bugs and to send donations.

The backend in server/ and the Forgejo integration are the work of this repository.