vite-plugin-css-injected-by-js weekly downloads statistics

vite-plugin-css-injected-by-js 🤯

A Vite plugin that bundles your CSS into JavaScript at build time, removing separate CSS files and enabling single-file deployments.

How does it work

By default, Vite extracts CSS into separate files during the build process. This plugin instead gathers all generated CSS and embeds it directly into the JavaScript bundle, injecting it at runtime. As a result, no standalone CSS file is produced and the corresponding <link> tag is removed from the generated HTML. You can also control the timing of the injection, specifying whether the styles should be applied before or after your application code executes.

Installation

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

or

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

or

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

Usage

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

export default defineConfig({
  plugins: [
    cssInjectedByJsPlugin()
  ]
})

By default, the CSS is injected automatically when the JavaScript bundle loads. If you need explicit control over when the CSS is injected (e.g. for Web Components, Shadow DOM, or SPAs that need to defer rendering), see the Virtual Module section below.

---

Virtual Module: On-Demand Injection

The plugin exposes an optional virtual module virtual:css-injected-by-js that gives you explicit control over when and where the bundled CSS is injected into the DOM.

When to use this

Use case	Recommended approach
Component-level granular lazy-loading	Vite's native ?inline query
Macro-level injection control (Library authors, Web Components, SPAs)	Virtual module virtual:css-injected-by-js

?inline vs Virtual Module: For component-level CSS that you want to control per-file, use Vite's built-in ?inline query (e.g. import css from './my.css?inline'). The virtual module is designed for macro-level control over the entire bundled CSS payload — deferring injection until your app is ready, or targeting a specific DOM node like a ShadowRoot.

Basic example

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

export default defineConfig({
  plugins: [
    cssInjectedByJsPlugin()
  ]
})

// src/main.ts
import { injectCSS, removeCSS } from 'virtual:css-injected-by-js'

// Your application setup...
const app = createApp()
app.mount('#app')

// Inject all bundled CSS when you're ready
injectCSS()

// If you need to clean the environment you can also remove the CSS
removeCSS()

⚠️ Advanced Configuration Limitations

When using the virtual:css-injected-by-js module, please be aware of the following architectural boundaries:

• topExecutionPriority is ignored: When using the virtual module, the plugin forces the injection payload to the absolute top of your chunks. This is mathematically required to ensure the CSS Queue is initialized before your application code calls injectCSS().
• Custom injectCode Boundaries: The removeCSS() function uses a synchronous MutationObserver on the target element. It will fail to track and remove your styles if your custom code:
  1. Injects into an element other than the configured target.
  2. Uses asynchronous logic (setTimeout, Promises, requestAnimationFrame).
  3. Uses Constructable Stylesheets (new CSSStyleSheet()) instead of actual DOM nodes.

Shadow DOM example

Pass a target option to inject the CSS into a ShadowRoot instead of document.head:

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

class MyWidget extends HTMLElement {
  connectedCallback() {
    const shadow = this.attachShadow({ mode: 'open' })
    shadow.innerHTML = `<div class="widget">Hello</div>`

    // Inject the bundled CSS into this Shadow DOM
    injectCSS({ target: shadow })
  }
}

customElements.define('my-widget', MyWidget)

Server-Side Rendering (SSR) extraction

In SSR environments (like Next.js, Nuxt, or custom Node servers), DOM methods like document.head.appendChild are not available. Calling injectCSS() will safely do nothing. Instead, you can extract the raw CSS string to manually inject it into your server-rendered HTML payload.

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

export function render() {
  const appHtml = renderToString(MyApp)
  const cssString = getRawCSS()

  return `
    <!DOCTYPE html>
    <html>
      <head>
        <style>\${cssString}</style>
      </head>
      <body>
        <div id="app">\${appHtml}</div>
      </body>
    </html>
  `
}

Note: In Vite Dev Mode (npm run dev), getRawCSS() will return an empty string because Vite handles CSS natively via HMR. Test your SSR CSS extraction using the production build (npm run build).

TypeScript support

The plugin ships type declarations for the virtual module. Add it to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["vite-plugin-css-injected-by-js/dist/esm/declarations/client"]
  }
}

The InjectCSSOptions interface:

declare module 'virtual:css-injected-by-js' {
  export interface InjectCSSOptions {
    /**
     * The DOM element where the <style> tag will be injected.
     * @default document.head
     */
    target?: HTMLElement | ShadowRoot;
  }

  export function injectCSS(options?: InjectCSSOptions): void;
  export function removeCSS(): void;
  
  /**
   * Returns the raw extracted CSS string. 
   * Highly useful for Server-Side Rendering (SSR) where DOM injection is impossible.
   */
  export function getRawCSS(): string;
}

How it works under the hood…