mjswensen/themer: one color set, themes for every app you open

The problem themer solves for people with too many config files

Anyone who has hand-tuned a Vim colorscheme, an iTerm profile, a VS Code theme and a desktop wallpaper knows the failure mode: the four drift apart. You change the background of the terminal, the editor still uses the old one, and the wallpaper was never in sync to begin with. Themer treats the color set as the source of truth and the per-app theme as a build artifact. You pick colors once, list the apps you want themes for, and the tool writes the files.

The audience is narrow and specific. It is for developers who keep their configuration in a repository and are willing to add a build step to it. The README's own example workflow installs themer inside a dotfiles directory and adds a script to package.json, which tells you the intended user already has that directory. If you configure your editor through a GUI and never touch a config file, the output is still usable, but the dotfiles integration that the README highlights is not available to you.

The project covers terminals, editors and IDEs, other apps such as Slack and Alfred, and desktop wallpapers. That breadth is the whole point. A single-color-set tool that only emitted VS Code themes would be a much smaller thing.

How the color set, template and output pipeline fits together

The architecture has three inputs and one output directory. A color set supplies the palette. A template knows how to turn that palette into a file for one target application. An optional size list supplies wallpaper resolutions in the form width x height. The CLI resolves all three and writes the rendered files plus a README explaining how to install them into the output directory, which defaults to themer-output.

Since V5 the package ships as a single TypeScript/JavaScript package that contains all the built-in color sets and templates, so the common case needs no separate downloads. The extension points are files rather than packages: --color-set accepts a path to a JavaScript file containing a custom color set, and --template accepts a path to a JavaScript file containing a custom template. Custom color sets are built from color mappings, which is the layer that decides which palette entry becomes a background, a foreground or an accent.

The API mirrors the CLI. Themer exposes a JavaScript API with TypeScript type definitions, so a build script can call it directly instead of shelling out. The repository layout reflects this split: cli/ and web/ sit at the top level, and the web application at themer.dev is the same engine behind a browser interface.

Installing themer and generating your first theme set

The README documents installation through npm. Install it as a project dependency or globally, or skip installation entirely with npx.

npm install themer

The CLI takes a color set, one or more templates, optional wallpaper sizes, and an output directory. Running it with no arguments uses the default color set and every built-in template, which is a large output if you only wanted one editor theme. The npx form below is the fastest way to see what the tool produces: it renders a Vim theme and the Block Wave wallpaper from the default color set into a folder named output.

npx themer -c default -t vim -t wallpaper-block-wave -o output

After the command finishes, open the output directory. You should find the generated theme files along with a README that documents how to install each one into its target application. That generated README is the part worth reading first, because it is per-template and tells you where the file belongs.

For a dotfiles repository, the README's example moves the command into package.json so the generation is repeatable. The script below is quoted from the README with the same flags and the same gen output directory.

{
  "scripts": {
    "build": "themer -c default -t vim -t vim-lightline -t hyper -t wallpaper-block-wave -o gen"
  }
}

Run npm run build, then inspect gen/. Note that -c, -t and -s may each be given more than once, so a single invocation can emit themes for several applications and several wallpaper resolutions at the same time.

Where the CLI falls short of the web app

The README publishes a feature comparison between the web UI and the CLI, and it is unusually honest. Instant preview is web only. The supported color format is any CSS format in the web UI but hex only on the CLI. Wallpaper output is PNG plus SVG in the browser and SVG only from the command line. Raytraced 3D wallpapers exist in the web UI and not in the CLI. Seamless dotfiles integration runs the other way: the CLI has it, the browser does not.

That table is the honest limitation of the command line. If your palette lives in oklch or hsl and you want to keep it that way, the CLI is the wrong entry point; you either convert to hex or use themer.dev. If you need a PNG wallpaper, the CLI will not produce one, and you would have to rasterize the SVG yourself. If the raytraced wallpaper style is what drew you to the project, the CLI cannot render it at all.

The other constraint is the release cadence. The most recent release listed is v6.0.0 from 2023-12-30, with v5.0.0 before it in 2023-02-25. The last push to the main branch was 2026-06-27, so the repository is not archived and work continues, but the packaged release history is sparse. Anyone who needs a template for an application released after 2023 should check whether that template exists before assuming it does.

How themer compares with base16 builders

The closest alternative in practice is the base16 ecosystem rather than a single named product. Base16 defines a fixed sixteen-color structure and a large collection of scheme files and per-application templates maintained across many separate repositories. Themer does not compete with that structure; it consumes it. The README documents passing a base16 scheme YAML file directly to --color-set in place of a themer color set.

The difference is in where the work happens. With base16 alone, you assemble the scheme and the template from different sources, and the template set is the community's, spread over many projects. With themer, the templates ship inside one npm package, the CLI resolves them by name, and the output directory plus its README are produced in one step. The trade-off is that themer's built-in template list is whatever the maintainers have written, while base16's coverage depends on whoever maintains each port. If your application has a base16 template but no themer template, the base16 route is the one that works today.

Licence and the cost of keeping themes in sync

Themer is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are included. The repository carries a LICENSE.md at the top level. This is a description of the licence text, not legal advice; if you redistribute themer inside a product, read the file yourself.

Upgrade cost is low in the ordinary case and rises with customization. Built-in color sets and templates come with the package, so moving to a newer version is a dependency bump. Custom color sets and custom templates are JavaScript files that you own, and the README does not document a stability guarantee for either interface, so a major version can change what those files are expected to export. The v5 to v6 step is the relevant precedent: V5 consolidated the previously separate color sets and templates into one package, which is exactly the kind of change that affects a build pipeline.

There is also a maintenance cost the tool cannot remove. Generated files are written to an output directory, but installing them into each application is still manual unless you script it. The generated README tells you where each file goes; wiring that into a dotfiles repository is your job.

Editorial conclusion

Adopt themer if you already keep dotfiles in a repository and want one color set to drive several apps at once; the CLI writes plain files and a README into the output directory, so nothing is hidden. Skip it if you need instant visual preview, non-hex color input, or a raytraced wallpaper, since the CLI supports hex colors and SVG wallpapers only. Before committing, run the default command and open the generated README to confirm every template you need is present, and check the last push date on the main branch, which was 2026-06-27, against your own tolerance for a project whose most recent release is v6.0.0 from 2023-12-30.

Frequently asked questions

Official sources

1. License: MIT
2. mjswensen/themer on GitHub
3. Project website
4. README
5. Releases