vite-plugin-shadow-style

1.2.0 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.2.0, stable) that injects CSS styles into web component shadow DOMs. It rewrites CSS imports to be available as a global SHADOW_STYLE string inside the component bundle, allowing styles to be appended to shadow roots without leaking. Differentiates from standard Vite CSS handling by targeting shadow DOM encapsulation. Ships TypeScript declarations.

Common errors

error Cannot find name 'SHADOW_STYLE'. ↓

cause TypeScript does not recognize the global SHADOW_STYLE variable injected by the plugin.

fix

Create a globals.d.ts file in your project root with: declare const SHADOW_STYLE: string;

error The requested module 'vite-plugin-shadow-style' does not provide an export named 'default' ↓

cause Trying to import a default export that doesn't exist.

fix

Use named import: import { shadowStyle } from 'vite-plugin-shadow-style'

error SHADOW_STYLE is not defined ↓

cause SHADOW_STYLE is a build-time injected global; it is not available at runtime in the dev server or if the plugin is not configured correctly.

fix

Ensure the plugin is added to build.rollupOptions.plugins in vite.config.ts and that you are building (not running dev server).

Warnings

gotcha SHADOW_STYLE is not imported; it's a global variable injected at build time. You must declare it in a .d.ts file for TypeScript to compile. ↓

fix Add a globals.d.ts file with: declare const SHADOW_STYLE: string;

gotcha The plugin should be added to rollupOptions.plugins, not the top-level plugins array in Vite config. ↓

fix Add shadowStyle() inside build.rollupOptions.plugins, as shown in the README.

gotcha If your component uses external CSS imports, Vite may bundle them as const declarations that can conflict when multiple components are imported. Use the iife option to wrap output in an IIFE to avoid global scope pollution. ↓

fix Pass { iife: true } to shadowStyle(): shadowStyle({ iife: true })

gotcha The plugin only works with Vite's build mode; dev server is not supported for SHADOW_STYLE injection. ↓

fix Use the plugin only for production builds. For development, consider an alternative or mock SHADOW_STYLE.

Install

npm install vite-plugin-shadow-style

yarn add vite-plugin-shadow-style

pnpm add vite-plugin-shadow-style

Imports

shadowStyle

wrong

import shadowStyle from 'vite-plugin-shadow-style'

correct

import { shadowStyle } from 'vite-plugin-shadow-style'

Named export only; no default export.

SHADOW_STYLE
wrong
```
import { SHADOW_STYLE } from 'vite-plugin-shadow-style'
```
correct
```
declare const SHADOW_STYLE: string; // in globals.d.ts
```
SHADOW_STYLE is a global variable injected by the plugin, not an import. You must declare it in a .d.ts file for TypeScript.

vite.config.ts usage

wrong

import shadowStyle from 'vite-plugin-shadow-style';
// then use shadowStyle() as a standalone function without plugin context

correct

import { shadowStyle } from 'vite-plugin-shadow-style';
export default defineConfig({ plugins: [shadowStyle()] })

The plugin returns a Vite plugin object; it must be added to the plugins array.

Quickstart

Configures the plugin in vite.config.ts, uses the global SHADOW_STYLE variable inside a web component, and declares the type for SHADOW_STYLE.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { shadowStyle } from 'vite-plugin-shadow-style';

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        react(),
        shadowStyle(),
      ],
    },
  },
});

// In your web component entry file (e.g., my-component.ts):
export class MyComponent extends HTMLElement {
  connectedCallback() {
    const style = document.createElement('style');
    style.innerHTML = SHADOW_STYLE; // injected by plugin
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(style);
    shadow.appendChild(document.createElement('div'));
  }
}

// globals.d.ts
declare const SHADOW_STYLE: string;