vite-plugin-theme

0.8.6 verified Mon Apr 27 auth: no javascript maintenance

Vite plugin for dynamically changing theme colors at runtime. Version 0.8.6 requires Vite >=2.0.0 and Node >=12.0.0. It extracts specified color variables from CSS output at build time, generating a separate theme stylesheet (app-theme-style.css) that can be dynamically swapped via JavaScript. Unlike CSS custom properties or runtime CSS-in-JS approaches, this plugin works with static CSS and supports deep customization options like custom selector resolution and variable extraction logic. Released under MIT, maintained by Vben Admin team. Not actively updated since mid-2023.

Common errors

error Error: The plugin is not compatible with Vite 3.0+ because of internal CSS processing changes. ↓

cause Vite 3+ changed CSS plugin internals, causing the plugin's hooks to fail.

fix

Use Vite 2.x or fork the plugin to adapt to newer Vite versions.

error [vite-plugin-theme] Cannot read properties of undefined (reading 'id') ↓

cause The plugin encounters a CSS transform for a non-file module (e.g., virtual module).

fix

Filter out virtual CSS modules in the plugin's transform hook or avoid using inline CSS from virtual modules.

Warnings

gotcha The plugin only extracts colors from static CSS files processed by Vite, not from inline styles or dynamically injected CSS. ↓

fix Ensure all theme-dependent styles are in CSS files (not inline) for extraction to work.

gotcha colorVariables must be exact color values (e.g., hex, rgb) as they appear in CSS; partial matches are not supported. ↓

fix Include the exact full color string (e.g., '#1890ff' not '#189') in colorVariables array.

gotcha The plugin generates a separate CSS file that must be loaded after the main stylesheet; incorrect injectTo position can cause flash of unstyled content. ↓

fix Use injectTo: 'head' or 'body-prepend' to control load order, or ensure main CSS loads before this file.

gotcha Does not support Vite 5+ or newer esbuild CSS minification features; may require workarounds for advanced CSS transforms. ↓

fix Test compatibility with your Vite version; consider using CSS custom properties for modern themes.

Install

npm install vite-plugin-theme

yarn add vite-plugin-theme

pnpm add vite-plugin-theme

Imports

viteThemePlugin

wrong

const viteThemePlugin = require('vite-plugin-theme').viteThemePlugin

correct

import { viteThemePlugin } from 'vite-plugin-theme'

Default export is named, not default. ESM-only, no CommonJS support.

mixLighten

wrong

import mixLighten from 'vite-plugin-theme'

correct

import { mixLighten } from 'vite-plugin-theme'

Utility function for color manipulation, exported as named export.

mixDarken

wrong

import { mixDarken } from 'vite-plugin-theme/mixDarken'

correct

import { mixDarken } from 'vite-plugin-theme'

Utility function for darkening colors, exported as named export.

Quickstart

Configures vite-plugin-theme in a Vite + Vue project, specifying colors to extract and dynamic injection options.

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteThemePlugin, mixLighten, mixDarken, tinycolor } from 'vite-plugin-theme';

export default defineConfig({
  plugins: [
    vue(),
    viteThemePlugin({
      colorVariables: [
        // CSS values to be dynamically replaced (e.g., primary color hex)
        '#1890ff',
        '#096dd9'
      ],
      wrapperCssSelector: 'body',
      injectTo: 'body',
      fileName: 'app-theme-style.hash.css',
      // Optional custom selector resolution
      resolveSelector: (selector) => selector,
    }),
  ],
});