vite-plugin-css-injected-by-js

5.0.1 verified Mon Apr 27 auth: no javascript

A Vite plugin that injects all CSS into the JavaScript bundle at build time, eliminating separate CSS files and enabling single-file deployments. Current stable version is 5.0.1, requiring Vite >8.0.0-0 (major breaking from v4 which supported Vite 4-7). It provides a virtual module for on-demand injection and supports custom injection targets like Shadow DOM. Key differentiator: unlike Vite's default CSS extraction, it bundles styles into JS, useful for widgets, libraries, or deployments where a single JS file is preferred. Ships TypeScript types. Active development with frequent releases.

Common errors

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

cause Trying to import the plugin as a named export instead of default.

fix

Use import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js' (no destructuring).

error Error: The virtual module 'virtual:css-injected-by-js' cannot be resolved. ↓

cause The plugin is not added to Vite plugins array or is added incorrectly.

fix

Ensure cssInjectedByJsPlugin() is in the plugins list in vite.config.ts.

error [vite] Internal server error: Unknown plugin option: topExecutionPriority ↓

cause Using an old option that was renamed or removed in current version.

fix

Check the documentation for v5 options; topExecutionPriority is still valid but verify usage.

error Module '"fsevents"' has not been loaded yet... ↓

cause Running on a non-macOS platform or missing native dependencies.

fix

Install optional dependencies with npm install or use pnpm install --shamefully-hoist.

Warnings

breaking Version 5.0.0 requires Vite >8.0.0-0, dropping support for Vite 4-7. Upgrade your Vite version or stay on v4. ↓

fix Update Vite to version 8+ or use vite-plugin-css-injected-by-js@^4

breaking Version 4.0.0 drops Node.js 14 support and changes plugin behavior for rolldown compatibility. ↓

fix Ensure Node.js >=16 and review any rolldown-specific configurations

gotcha When using virtual:css-injected-by-js module, topExecutionPriority option is ignored. The plugin forces injection payload to the top of chunks. ↓

fix If you rely on topExecutionPriority, avoid using the virtual module.

gotcha removeCSS() uses MutationObserver and fails if custom injectCode uses async logic, different target element, or Constructable Stylesheets. ↓

fix Ensure custom injection is synchronous, targets the same element, and uses DOM nodes, not CSSStyleSheet.

deprecated The 'uniqueCSS' option was removed in v3.0.0. CSS is always unique now. ↓

fix Remove uniqueCSS option from plugin configuration.

Install

npm install vite-plugin-css-injected-by-js

yarn add vite-plugin-css-injected-by-js

pnpm add vite-plugin-css-injected-by-js

Imports

default

wrong

import { cssInjectedByJsPlugin } from 'vite-plugin-css-injected-by-js'

correct

import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'

The plugin is exported as default; named export also exists but default is typical.

injectCSS

wrong

import { injectCSS } from 'vite-plugin-css-injected-by-js'

correct

import { injectCSS } from 'virtual:css-injected-by-js'

injectCSS is a virtual module export, not from the package itself.

removeCSS

wrong

import { removeCSS } from 'vite-plugin-css-injected-by-js'

correct

import { removeCSS } from 'virtual:css-injected-by-js'

Also part of the virtual module for cleanup.

Quickstart

Basic setup: install plugin, import default export, add to Vite config, and build to get a single JS file with CSS injected.

// vite.config.ts
import { defineConfig } from 'vite'
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'

export default defineConfig({
  plugins: [
    // Removes external CSS files and injects all CSS into the JS bundle
    cssInjectedByJsPlugin({ topExecutionPriority: true })
  ]
})