npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

themer

v6.7.0

Published

Customizable theme generator for editors, terminals, wallpaper, and more.

Downloads

1,072

Readme

themer GitHub Workflow Status (main branch) Follow on Mastodon Join the newsletter

themer takes a set of colors and generates editor themes, terminal themes, themes for other apps, and desktop wallpapers.

visual description

Table of contents

Getting started

There are a few different ways to level up your development setup with themer:

  1. Web-based graphical user interface. themer has an official progressive web app located at themer.dev.
  2. Command-line interface. themer can be used to generate themes on the CLI, see the CLI docs below.
  3. Application programming interface. themer exposes a JavaScript API (complete with TypeScript type definitions) for programmatic use; see the API docs below.

Feature comparison:

| | Web UI | CLI/API | | ----------------------------- | -------------- | -------- | | Instant preview | ✅ | ❌ | | Premium color sets | ✅ | ❌ | | Supported color format | Any CSS format | Hex only | | Wallpaper output format | PNG + SVG | SVG only | | Seamless dotfiles integration | ❌ | ✅ |

CLI documentation

As of V5, themer is distributed as a single TypeScript/JavaScript package containing all built-in color sets and templates for ease of use—but still supports the use of custom color sets or templates.

Installation

Install themer from npm with your JavaScript package manager of choice.

npm install themer

themer can also be installed globally. Or if you prefer not to install it at all, it can be used with npx.

Usage

themer [options]

Pass themer one or more color sets, as many templates as you wish, as many wallpaper resolutions as you wish, and an output directory.

| Option | Description | Default value | Available options | | ----------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -c, --color-set <built-in color set name or file path...> | the color set(s) to render | default | color set name, or path to JS file containing a custom color set, or a file path to a base16 yaml file | | -t, --template <built-in template name or file path...> | the theme template(s) to render | * (all built-in templates) | template name, or path to JS file containing a custom template | | -s, --size <wallpaper resolution...> | resolution to render in pixels, in the format [width]x[height] | 2880x1800 | any | | -o, --output <path> | the output directory | themer-output | any |

--color-set, --template, and --size may be specified multiple times.

Your generated theme files, as well as a README on how to install them, will be written to the output directory.

Example workflow: dotfiles integration

Say you wanted to generate a vim theme and desktop background using themer's default color set. First, install themer:

cd my-dotfiles
npm install themer

Then edit your package.json:

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

Then run your new script:

npm run build

Now check the gen/ folder for your generated files. Here's the result:

example usage result

Example workflow: npx

This command will generate a Vim theme and the Block Wave wallpaper, using themer's default color set, and put them in a folder called output:

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

Example workflow: using base16 schemes with Themer

In place of a themer color set, you can also provide themer with any base16 scheme YAML file.

themer --color-set path/to/base16-scheme.yml ...

Refer to the base16 repository for a list of base16 schemes.

API documentation

themer ships with a JavaScript API (with TypeScript type definitions) for use in programmatically generating themes.

Installation

npm install themer

Interface

themer's default export is an async generator function that takes three arguments:

  1. An array of ColorSet objects, or string identifiers of themer's built-in color sets
  2. An array of Template objects, or string identifiers of themer's built-in templates
  3. A RenderOptions object used to specify the resolution of the outputted wallpaper images
  4. (Optional) an OutputFileTransform async generator function that transforms the files generated by the provided templates. This function runs between each template's render and renderInstructions functions.

The objects yielded by the generator are OutputFiles or the type yielded by OutputFileTransform.

import themer from "themer";
import myColors from "./my-colors";
import myTemplate from "./my-template";

// Example usage: generate Vim themes, 1440x900 wallpapers, and custom files
// from themer's "Night Sky" color set and a custom color set.
const files = themer(
  ["night-sky", myColors],
  ["vim", "wallpaper-block-wave", myTemplate],
  { wallpaperSizes: [{ width: 1440, height: 900 }] }
);

for await (const file of files) {
  // ...
}

Create custom ColorSets

import type { ColorSet } from "themer";

const myColorSet: ColorSet = {
  // Color sets should provide a human-readable name.
  name: "My Color Set",

  // Color sets can define a dark variant, a light variant, or both.
  // Each variant provides two or eight shades and eight accent colors in hex format.
  variants: {
    // In a dark variant, shade0 should be the darkest and shade7 should be
    // the lightest.
    dark: {
      shade0: "#333333",
      // Note: you can define shades 1 through 6 yourself, or you can omit
      // them; if omitted, they will be calculated automatically by
      // interpolating between shade0 and shade7.
      shade7: "#eeeeee",
      accent0: "#ff4050",
      accent1: "#f28144",
      accent2: "#ffd24a",
      accent3: "#a4cc35",
      accent4: "#26c99e",
      accent5: "#66bfff",
      accent6: "#cc78fa",
      accent7: "#f553bf",
    },

    // In a light variant, shade7 should be the darkest and shade0 should be
    // the lightest.
    light: {
      shade0: "#eeeeee",
      shade7: "#333333",
      accent0: "#f03e4d",
      accent1: "#f37735",
      accent2: "#eeba21",
      accent3: "#97bd2d",
      accent4: "#1fc598",
      accent5: "#53a6e1",
      accent6: "#bf65f0",
      accent7: "#ee4eb8",
    },
  },
};

export default myColorSet;

Pro Tip: you can use themer's Web UI to more easily select your colors, then click the "Download" button to generate a colors.js file in the correct format. With the Web UI, you can also input any valid CSS color format (keyword, HSL, RGB, etc.) and it will automatically convert the color to hex for you.

Color mappings

To help you choose colors for your own color set, this is approximately how most themer templates will utilize your colors:

| Color Key | Typical Usage | Conventional Color* | | --------- | ------------------------- | -------------------- | | accent0 | error, VCS deletion | Red | | accent1 | syntax | Orange | | accent2 | warning, VCS modification | Yellow | | accent3 | success, VCS addition | Green | | accent4 | syntax | Cyan | | accent5 | syntax | Blue | | accent6 | syntax, caret/cursor | | | accent7 | syntax, special | Magenta | | shade0 | background color | | | shade1 | UI | | | shade2 | UI, text selection | | | shade3 | UI, code comments | | | shade4 | UI | | | shade5 | UI | | | shade6 | foreground text | | | shade7 | foreground text | |

*Conventional color is suggested for consistency with ANSI color names in terminal themes, but is not a hard requirement.

See themer's Web UI for a more visual representation of the color mappings.

Create custom Templates

import type { Template } from "themer";

const template: Template = {
  // Templates should provide a human-readable name.
  name: "My Template",

  // The render async generator function takes a color set and the render
  // options, and yields one or more output files. The color set is fully
  // expanded (e.g., if the color set did not include shades 1 through 6
  // when originally authored, those intermediary shades will have already
  // been calculated and included).
  render: async function* (colorSet, options) {
    // The yielded output file has two properties: a string path (relative)
    // and a Buffer of the file's content.
    yield {
      path: "my-file.txt",
      content: Buffer.from("Hello, world!", "utf8"),
    };
  },

  // The renderInstructions function takes an array of paths generated from
  // the render function and should return a Markdown string, which will be
  // included in the generated README.md file.
  renderInstructions: (paths) =>
    `Copy the files (${paths.join(" and ")}) to your home directory.`,
};

export default template;

Themer color sets

Premium color sets

(Only available on themer.dev.)

| Name | Dark Preview | Light Preview | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Jamstacker | Jamstacker dark preview | (dark only) | | Victor Mono | Victor Mono dark preview | Victor Mono light preview | | Future Pro | Future Pro dark preview | Future Pro light preview |

Original color sets

| Name | Dark Preview | Light Preview | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | default | default dark preview | default light preview | | finger-paint | finger-paint dark preview | finger-paint light preview | | green-as-a-whistle | green-as-a-whistle dark preview | green-as-a-whistle light preview | | monkey | monkey dark preview | monkey light preview | | night-sky | night-sky dark preview | (dark only) | | polar-ice | polar-ice dark preview | polar-ice light preview | | right-in-the-teals | right-in-the-teals dark preview | right-in-the-teals light preview | | shoulder-pads | shoulder-pads dark preview | shoulder-pads light preview |

Ports from third-party themes

| Name | Dark Preview | Light Preview | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | dracula | dracula dark preview | (dark only) | | github-universe | github-universe dark preview | (dark only) | | lucid | lucid dark preview | lucid light preview | | mojave | mojave dark preview | mojave light preview | | nova | nova dark preview | (dark only) | | one | one dark preview | one light preview | | rivet | rivet dark preview | rivet light preview | | seti | seti dark preview | (dark only) | | solarized | solarized dark preview | solarized light preview |

Themer templates

Terminals

Editors/IDEs

Other apps

Wallpapers

See themer's Web UI for wallpaper previews.

Prior art

themer is inspired by trevordmiller/nova and chriskempson/base16.

Conceptually, themer is very similar to base16, but:

  1. It is lighter, and simpler to use.
  2. It is more easily extensible with your own color sets and templates.
  3. It integrates better with your dotfiles, especially if you keep them under version control.

Contributing

For instructions on how to contribute to themer, see CONTRIBUTING.md and themer's code of conduct.

Next steps

Join the community

Support themer