vite-theme-color-replacer

1.0.36 verified Mon Apr 27 auth: no javascript

A Vite plugin for dynamically changing CSS theme colors at runtime without reload. Version 1.0.36, released under MIT. It extracts CSS rules containing specified colors during build and generates a separate CSS file that can be swapped in the browser. Supports hex, rgb, hsl color formats, works with Element UI/Element Plus via built-in utilities, and offers optional CSS injection or external file processing. Differentiates from CSS variables-based themes by targeting pre-existing selectors with high specificity. Requires Vite ^4.0.0, ^5.0.0, or ^6.0.0 as a peer dependency.

Common errors

error Cannot find module 'vite-theme-color-replacer/forElementUI' ↓

cause The subpath 'forElementUI' is not included when installed without TypeScript declaration files or with a bundler that doesn't resolve it.

fix

Ensure your project is using ESM (type: module in package.json) and your bundler supports package.json exports. Or use a newer version of vite-theme-color-replacer.

error TypeError: Cannot read properties of undefined (reading 'map') ↓

cause The 'matchColors' option is missing or is not an array of strings.

fix

Provide an array of color strings, e.g., matchColors: ['#409EFF', '#1890ff']

error The 'newColors' argument must be an array of strings matching matchColors length. ↓

cause Number of new colors does not match the number of extracted colors at build time.

fix

Get new colors using the same function that generated matchColors, e.g., getElementUISeries(newPrimaryColor).

error Failed to load theme-colors CSS: net::ERR_ABORTED 404 ↓

cause The generated theme CSS file URL is incorrect in the running environment (e.g., base path mismatch).

fix

Use the 'changeUrl' option in changer.changeColor to adjust the URL, or ensure the CSS file is served correctly.

Warnings

gotcha If you use 'injectCss: true', the theme CSS is inlined and the fileName option is ignored. ↓

fix Set injectCss: false if you want a separate CSS file.

breaking v1.0.36 changed internal handling of color formats; old colors in RGB format may not match extracted CSS. ↓

fix Double-check matchColors: use hex strings for easier matching.

deprecated The 'oldColors' option in changer.changeColor is deprecated; the plugin now extracts old colors automatically. ↓

fix Remove oldColors from changeColor calls.

gotcha If you use 'externalCssFiles' with a path that doesn't exist at build time, the plugin will throw an error. ↓

fix Ensure paths in externalCssFiles are correct relative to project root.

gotcha When using 'changeSelector', the selector utility is limited to adding prefixes; complex transformations may fail. ↓

fix Refer to the util API; avoid using regex replacements on the full selector string.

Install

npm install vite-theme-color-replacer

yarn add vite-theme-color-replacer

pnpm add vite-theme-color-replacer

Imports

default export (plugin)

wrong

const viteThemeColorReplacer = require('vite-theme-color-replacer')

correct

import viteThemeColorReplacer from 'vite-theme-color-replacer'

ESM-only; types included

getElementUISeries

wrong

import { getElementUISeries } from 'vite-theme-color-replacer'

correct

import { getElementUISeries } from 'vite-theme-color-replacer/forElementUI'

Utility is in separate subpath; not exported from main entry

changer (runtime client)

wrong

import { changer } from 'vite-theme-color-replacer'

correct

import { changer } from 'vite-theme-color-replacer/client'

Runtime API is in client subpath; not available server-side

changeElementUISelector
```
import { changeElementUISelector } from 'vite-theme-color-replacer/forElementUI'
```
Only for Element UI; different UI frameworks need custom selectors

Quickstart

Shows Vite plugin configuration with Element UI series and runtime color change using the client API.

// vite.config.ts
import { defineConfig } from 'vite';
import viteThemeColorReplacer from 'vite-theme-color-replacer';
import { getElementUISeries } from 'vite-theme-color-replacer/forElementUI';

export default defineConfig({
  plugins: [
    viteThemeColorReplacer({
      matchColors: getElementUISeries('#409EFF'),
      fileName: 'css/theme-colors-[contenthash:8].css',
      injectCss: false,
    }),
  ],
});

// client.js
import { changer } from 'vite-theme-color-replacer/client';
import { getElementUISeries } from 'vite-theme-color-replacer/forElementUI';

async function changeTheme(newPrimaryColor: string) {
  const newColors = getElementUISeries(newPrimaryColor);
  await changer.changeColor({ newColors, appendToEl: 'body' });
}
changeTheme('#f56c6c');