{"id":22951,"library":"vite-theme-color-replacer","title":"vite-theme-color-replacer","description":"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.","status":"active","version":"1.0.36","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","vite","theme","color","replacer","runtime","dynamic","element-ui","element-plus","typescript"],"install":[{"cmd":"npm install vite-theme-color-replacer","lang":"bash","label":"npm"},{"cmd":"yarn add vite-theme-color-replacer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-theme-color-replacer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: required as a Vite plugin","package":"vite","optional":false}],"imports":[{"note":"ESM-only; types included","wrong":"const viteThemeColorReplacer = require('vite-theme-color-replacer')","symbol":"default export (plugin)","correct":"import viteThemeColorReplacer from 'vite-theme-color-replacer'"},{"note":"Utility is in separate subpath; not exported from main entry","wrong":"import { getElementUISeries } from 'vite-theme-color-replacer'","symbol":"getElementUISeries","correct":"import { getElementUISeries } from 'vite-theme-color-replacer/forElementUI'"},{"note":"Runtime API is in client subpath; not available server-side","wrong":"import { changer } from 'vite-theme-color-replacer'","symbol":"changer (runtime client)","correct":"import { changer } from 'vite-theme-color-replacer/client'"},{"note":"Only for Element UI; different UI frameworks need custom selectors","wrong":null,"symbol":"changeElementUISelector","correct":"import { changeElementUISelector } from 'vite-theme-color-replacer/forElementUI'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport viteThemeColorReplacer from 'vite-theme-color-replacer';\nimport { getElementUISeries } from 'vite-theme-color-replacer/forElementUI';\n\nexport default defineConfig({\n  plugins: [\n    viteThemeColorReplacer({\n      matchColors: getElementUISeries('#409EFF'),\n      fileName: 'css/theme-colors-[contenthash:8].css',\n      injectCss: false,\n    }),\n  ],\n});\n\n// client.js\nimport { changer } from 'vite-theme-color-replacer/client';\nimport { getElementUISeries } from 'vite-theme-color-replacer/forElementUI';\n\nasync function changeTheme(newPrimaryColor: string) {\n  const newColors = getElementUISeries(newPrimaryColor);\n  await changer.changeColor({ newColors, appendToEl: 'body' });\n}\nchangeTheme('#f56c6c');","lang":"typescript","description":"Shows Vite plugin configuration with Element UI series and runtime color change using the client API."},"warnings":[{"fix":"Set injectCss: false if you want a separate CSS file.","message":"If you use 'injectCss: true', the theme CSS is inlined and the fileName option is ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check matchColors: use hex strings for easier matching.","message":"v1.0.36 changed internal handling of color formats; old colors in RGB format may not match extracted CSS.","severity":"breaking","affected_versions":">=1.0.36"},{"fix":"Remove oldColors from changeColor calls.","message":"The 'oldColors' option in changer.changeColor is deprecated; the plugin now extracts old colors automatically.","severity":"deprecated","affected_versions":">=1.0.30"},{"fix":"Ensure paths in externalCssFiles are correct relative to project root.","message":"If you use 'externalCssFiles' with a path that doesn't exist at build time, the plugin will throw an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the util API; avoid using regex replacements on the full selector string.","message":"When using 'changeSelector', the selector utility is limited to adding prefixes; complex transformations may fail.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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.","cause":"The subpath 'forElementUI' is not included when installed without TypeScript declaration files or with a bundler that doesn't resolve it.","error":"Cannot find module 'vite-theme-color-replacer/forElementUI'"},{"fix":"Provide an array of color strings, e.g., matchColors: ['#409EFF', '#1890ff']","cause":"The 'matchColors' option is missing or is not an array of strings.","error":"TypeError: Cannot read properties of undefined (reading 'map')"},{"fix":"Get new colors using the same function that generated matchColors, e.g., getElementUISeries(newPrimaryColor).","cause":"Number of new colors does not match the number of extracted colors at build time.","error":"The 'newColors' argument must be an array of strings matching matchColors length."},{"fix":"Use the 'changeUrl' option in changer.changeColor to adjust the URL, or ensure the CSS file is served correctly.","cause":"The generated theme CSS file URL is incorrect in the running environment (e.g., base path mismatch).","error":"Failed to load theme-colors CSS: net::ERR_ABORTED 404"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}