vite-plugin-css-position

2.0.9 verified Mon Apr 27 auth: no javascript

A Vite plugin (v2.0.9) that gives React and Vue developers precise control over where CSS stylesheets are injected in the component tree, addressing a common pain point with Shadow DOM and scoped styles. Unlike traditional CSS injection at the document head, this plugin allows placement at any arbitrary location via the StylesTarget component. It ships TypeScript types, supports HMR in dev mode when enabled, and has zero runtime dependencies beyond peer requirements (React 19 / Vue 3.5.22). Semi-active development with monthly releases. Differentiator: fine-grained DOM insertion point control without ejecting from Vite.

Common errors

error SyntaxError: Named export 'viteCssPosition' not found. The requested module 'vite-plugin-css-position' is a CommonJS module... ↓

cause Using require() or misconfigured module resolution (CommonJS vs ESM).

fix

Use import { viteCssPosition } from 'vite-plugin-css-position'; and ensure your Vite config or tsconfig has 'moduleResolution' set to 'bundler' or 'node16'.

error Module not found: Error: Can't resolve 'vite-plugin-css-position/react' ↓

cause The package subpath export for the framework-specific component is not recognized because the package.json 'exports' field may not be supported by your bundler/node version.

fix

Upgrade Node to >=14.13 or use a bundler that supports the 'exports' field (Vite, webpack 5, etc.). Alternatively, import from 'vite-plugin-css-position/dist/react.js' as a fallback.

error Warning: ReactDOM is injecting styles into the head even though StylesTarget is present. ↓

cause The plugin is not properly configured or there is another CSS injection mechanism (e.g., style-loader) overriding it.

fix

Ensure viteCssPosition() is added to plugins array before react() or vue() plugin. Also check that 'enableDev' is set to true in development.

Warnings

breaking Dropped support for React 17 and 18 in v2.x; requires React 19 or Vue 3.5.22+. ↓

fix Upgrade to React 19 or Vue 3.5.22+. If you must use older versions, stick to v1.x.

gotcha The plugin does not inject styles during development unless 'enableDev' option is set to true. Missing HMR in dev by design to avoid flicker. ↓

fix Set enableDev: true in viteCssPosition options to enable development injection and HMR.

deprecated The option 'customId' was renamed to 'instanceId' in v2.0.0. ↓

fix Use 'instanceId' instead of 'customId'.

gotcha Place StylesTarget inside a parent <div> or container; placing it as the root element may cause unexpected behavior because the component needs a parent node to target insertion. ↓

fix Always wrap StylesTarget in a parent element (e.g., <div><StylesTarget /></div>).

breaking Peer dependency on React 19 vs Vue 3.5.22 — if both are present, behavior is undefined; the plugin picks one based on import order. ↓

fix Use only React or only Vue in a project. Do not mix frameworks.

Install

npm install vite-plugin-css-position

yarn add vite-plugin-css-position

pnpm add vite-plugin-css-position

Imports

viteCssPosition
wrong
```
import viteCssPosition from 'vite-plugin-css-position'
```
correct
```
import { viteCssPosition } from 'vite-plugin-css-position'
```
viteCssPosition is a named export, not default. Also do not use require() as the package is ESM-only.
StylesTarget (React)
wrong
```
import StylesTarget from 'vite-plugin-css-position'
```
correct
```
import StylesTarget from 'vite-plugin-css-position/react'
```
StylesTarget is exported from the subpath for each framework. For React, import from 'vite-plugin-css-position/react'. For Vue, import from 'vite-plugin-css-position/vue'.

StylesTarget (Vue)

wrong

import StylesTarget from 'vite-plugin-css-position'

correct

import StylesTarget from 'vite-plugin-css-position/vue'

Same as React, the Vue component is in a separate subpath export.

Quickstart

Shows Vite plugin configuration and usage of StylesTarget component in a React app.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteCssPosition } from 'vite-plugin-css-position';

export default defineConfig({
  plugins: [
    react(),
    viteCssPosition({ enableDev: true }), // enableDev for HMR in dev
  ],
});

// App.tsx
import StylesTarget from 'vite-plugin-css-position/react';

export function App() {
  return (
    <div>
      <StylesTarget />
      <span>Your App Content</span>
    </div>
  );
}