Plugins

Extend Themvora with plugins

Themvora's plugin system lets you hook into every stage of the theme lifecycle — from runtime creation to token transforms to persistence. Plugins are small, composable objects that follow a single ThemePlugin interface.

Prerequisites

Runtime concepts

Understand how the theme runtime works

TypeScript basics

Plugins use the ThemePlugin interface

1What is a Plugin?

A plugin is an object with a name, an optional version and priority, and any combination of lifecycle hooks.

Every plugin implements the ThemePlugin interface. At minimum, a plugin needs a name — everything else is optional. Plugins are registered when the runtime is created and can be managed dynamically via the PluginManager.

defining a basic plugin

import type { ThemePlugin } from "@themvora/core";

const myPlugin: ThemePlugin = {
  name: "my-plugin",
  version: "1.0.0",
  priority: 10,

  onRuntimeCreated(runtime) {
    console.log("Runtime ready", runtime);
  },

  onAfterThemeChange({ theme }) {
    console.log("Theme changed to", theme.name);
  },
};

2Plugin Hooks

Lifecycle hooks fire at predictable points during the theme runtime's lifetime.

onRuntimeCreated

Called once when the runtime finishes initialization.

onBeforeThemeChange

Fires before the active theme switches.

onAfterThemeChange

Fires after the new theme is active.

onBeforePersist

Fires before the selection is saved.

onAfterPersist

Fires after the selection has been persisted.

onBeforeApply

Fires before CSS variables are written to the DOM.

onAfterApply

Fires after CSS variables have been applied.

onDestroy

Called when the runtime is destroyed.

onRuntimeCreated can return a teardown |If the hook returns a function, it will be called when the runtime is destroyed — useful for cleaning up subscriptions.

3Token Transforms

Transform tokens before they reach the DOM — override, augment, or remap any token path.

The transformTokens hook receives the full token object and the current theme, and must return the (potentially modified) tokens. Multiple transform plugins chain in priority order — each receives the output of the previous.

token transform plugin

import type { ThemePlugin, ThemeTokens } from "@themvora/core";

const contrastBoost: ThemePlugin = {
  name: "contrast-boost",
  priority: 5,

  transformTokens(tokens, { theme }) {
    // Adjust foreground tokens for better contrast.
    if (theme.meta?.mode === "dark") {
      return {
        ...tokens,
        colors: {
          ...tokens.colors,
          foreground: adjustBrightness(tokens.colors.foreground, 10),
        },
      };
    }
    return tokens;
  },
};

4Priority & Ordering

The priority field controls plugin execution order — lower values run first.

priority defaults to 10 when omitted.
Lower values execute first — a plugin with priority 0 runs before one with 10.
Plugins with the same priority run in registration order.
transformTokens hooks chain in priority order — each plugin sees the previous output.

priority ordering

import type { ThemePlugin } from "@themvora/core";

const pluginA: ThemePlugin = {
  name: "a",
  priority: 0,   // Runs first
  transformTokens(tokens) { /* … */ return tokens; },
};

const pluginB: ThemePlugin = {
  name: "b",
  // priority defaults to 10
  transformTokens(tokens) { /* … */ return tokens; },
};

const pluginC: ThemePlugin = {
  name: "c",
  priority: 20,  // Runs last
  transformTokens(tokens) { /* … */ return tokens;
};

// Execution order: A → B → C
// Lower priority values execute first.
// Plugins with the same priority run in registration order.

5Runtime Integration

Manage plugins at runtime with the PluginManager — register, look up, remove, and destroy.

Plugins are passed at runtime creation via the plugins option. For dynamic management, use createPluginManager() to create a standalone manager, or call runtime.destroy() to tear down all registered plugins.

runtime plugin management

TS / JS

import { createThemeRuntime, createPluginManager } from "@themvora/core";

const runtime = createThemeRuntime({
  plugins: [debuggerPlugin, persistencePlugin],
});

// Standalone plugin manager
const manager = createPluginManager();

// Register a plugin — returns an unsubscribe function
const unsubscribe = manager.use(myPlugin);

// Look up a registered plugin by name
const found = manager.get("my-plugin");

// Remove a plugin by name
manager.remove("my-plugin");

// List all registered plugins (sorted by priority)
const all = manager.list();

// Destroy all plugins and call their onDestroy hooks
manager.destroy();

// Unsubscribe to remove the plugin later
unsubscribe();

Duplicate names are skipped |Registering a plugin with a name that is already registered logs a warning and returns a no-op unsubscribe function.

6Full Example

A complete plugin that dispatches custom events on theme changes and boosts contrast on dark tokens.

full plugin example

import type { ThemePlugin, ThemeTokens } from "@themvora/core";

/**
 * Logs every theme change and boosts contrast on dark tokens.
 */
const analyticsPlugin: ThemePlugin = {
  name: "theme-analytics",
  version: "1.0.0",
  priority: 5,

  onRuntimeCreated(runtime) {
    const unsubscribe = runtime.store.subscribe((theme) => {
      window.dispatchEvent(
        new CustomEvent("theme-change", { detail: theme.name }),
      );
    });
    return unsubscribe;
  },

  onBeforeThemeChange({ current, next }) {
    console.log(
      `[theme-analytics] ${current.name} → ${next.name}`,
    );
  },

  onAfterApply({ theme }) {
    console.log(`[theme-analytics] Applied ${theme.name}`);
  },

  transformTokens(tokens: ThemeTokens, { theme }) {
    if (theme.meta?.mode === "dark") {
      return {
        ...tokens,
        colors: {
          ...tokens.colors,
          foreground: tokens.colors.foreground ?? "#f5f5f5",
        },
      };
    }
    return tokens;
  },

  onDestroy() {
    console.log("[theme-analytics] Destroyed");
  },
};

// Pass to the runtime at creation
import { createThemeRuntime } from "@themvora/core";

const runtime = createThemeRuntime({
  plugins: [analyticsPlugin],
});

7API reference

Every export used on this page is documented in the generated reference — this guide links it rather than duplicating it.

The full surface, generated from source JSDoc:

@themvora/core API reference

Next steps

Explore DOM adapters

Customize how themes are applied to the DOM

→

Understand token resolution

Hook into the resolution pipeline with transformTokens

→