karabiner.ts

Write Karabiner-Elements configuration in TypeScript.

Note

Use of TypeScript is optional. Config can also be written in JavaScript. Only the basics of JavaScript are needed. Check out my interactive course at codojo.dev.

Why karabiner.ts

karabiner.ts is heavily inspired by Goku. Compared to the edn format, it allows for:

• Easier-to-understand TypeScript/JavaScript syntax
• Strong-typed abstractions and key aliases with IDE support
• Structured config files instead of one big file

And more features (abstractions) (hyperLayer, duoLayer, leaderMode, ...).

Learn More

• 📝 Docs
• 🔧 My Config
• 💡 In-the-wild usage

Using the Online Editor

1. Write config in the online editor. (Optional: fork the editor to save the config for later editing)
2. Copy the generated JSON then add to Karabiner-Elements.

Note

Importing JSON to Karabiner-Elements is only needed when using the Online Editor. karabiner.ts writes to ~/.config/karabiner/karabiner.json if using with Node.js or Deno.

Karabiner-Elements watches ~/.config/karabiner/karabiner.json and reloads it if updated.

Using Node.js

Option 1

npx create-karabiner-config@latest

The default directory name is karabiner-config. You can pass another project-name:

npx create-karabiner-config@latest [project-name]

Then:

1. Write your key mapping in src/index.ts.
2. Set the profile name. Create a new Karabiner-Elements profile if needed.
3. Run npm run build.

To update to the latest version, run npm run update (or npm update karabiner.ts).

Option 2

1. Download (or clone | fork) the examples/starter repo.
2. Run npm install.

Then write and build the config same as Option 1.

Option 3

npm install karabiner.ts

(or install with yarn, pnpm, etc) then call writeToProfile() from any Node.js script in your preferred way.

Using Deno

In a Deno script file (replace {version}):

import { rule, writeToProfile } from 'https://deno.land/x/karabinerts@{version}/deno.ts'

writeToProfile('Default', [
  // rule(...
])

Then run it with:

deno run --allow-env --allow-read --allow-write {filename}