Registry / web-framework / vite-plugin-lazy-css-modules-inliner

vite-plugin-lazy-css-modules-inliner

library0.2.0jsnpmunverified

A Vite plugin (v0.2.0) that enables true on-demand CSS injection for dynamically imported code by virtualizing CSS Modules. It prevents lazy components' styles from being bundled into the page's initial CSS, injecting them only when the corresponding JavaScript chunk is actually loaded. Supports Vite 4+, TypeScript, and frameworks like React, Vue, Svelte (via external *.module.css imports). Unlike typical CSS-in-JS solutions or code-splitting plugins, it preserves CSS Modules hashing, avoids preloading CSS via __vitePreload, and includes built-in RTL support via runtimeIsRtlCondition. Released as a proof-of-concept with active maintenance.

web-framework serialization

npm install vite-plugin-lazy-css-modules-inliner

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-LAZY-C

vite-plugin-lazy-css-modules-inliner

web-frameworkjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

viteLazyCssInliner

✓ import { viteLazyCssInliner } from 'vite-plugin-lazy-css-modules-inliner'

✗ const viteLazyCssInliner = require('vite-plugin-lazy-css-modules-inliner')

ESM-only; package ships TypeScript types and uses ESM exports. CommonJS require will fail as package.json has "type": "module".

PluginOptions

✓ import type { PluginOptions } from 'vite-plugin-lazy-css-modules-inliner'

✗ import { PluginOptions } from 'vite-plugin-lazy-css-modules-inliner'

PluginOptions is a TypeScript interface used for type annotations only; importing it as a value will cause a runtime error.

default import

✓ import viteLazyCssInliner from 'vite-plugin-lazy-css-modules-inliner'

✗ import { default as viteLazyCssInliner } from 'vite-plugin-lazy-css-modules-inliner'

Package does not export a default export; using default import will result in undefined. Only named export is available.

VitePlugin

✓ import { viteLazyCssInliner } from 'vite-plugin-lazy-css-modules-inliner'

✗ import VitePlugin from 'vite-plugin-lazy-css-modules-inliner'

No default export; the correct import uses the named export 'viteLazyCssInliner'.

Shows basic setup with vite.config.ts plugin initialization and a lazy-loaded React component using CSS Modules. The plugin intercepts dynamic imports to inline CSS only when the component is actually rendered.

// vite.config.ts import { defineConfig } from 'vite'; import { viteLazyCssInliner } from 'vite-plugin-lazy-css-modules-inliner'; export default defineConfig({ plugins: [ viteLazyCssInliner({ stripPreloadDepsMode: 'css', // default isDev: process.env.NODE_ENV !== 'production', includedPathes: ['src'], excludedPathes: ['node_modules'], }), ], }); // MyComponent.jsx import styles from './MyComponent.module.css'; const MyComponent = () => <div className={styles.root}>Hello</div>; export default MyComponent;

Debug

Known issues

breakingrequires node >= 18 and vite >= 4

fix

Update Node.js to 18+ and Vite to 4+. Check engines field in package.json.

affects: >=0.0.0

deprecatedstripPreloadDepsMode: 'all' may cause unexpected behavior in shared chunks

fix

Use 'css' (default) unless you fully understand the implications. 'all' strips all dependencies from __vitePreload which can break chunk loading.

affects: >=0.2.0

gotchaMixed static and dynamic imports of the same CSS module can duplicate CSS

fix

Use only dynamic imports for CSS modules that are lazy-loaded, or accept the duplication. Do not mix import styles for the same module.

affects: >=0.0.0

gotchaThe plugin re-routes CSS imports inside lazy graphs to virtual modules; if you see 'Cannot find module' errors for virtual IDs, your bundler may not support virtual modules

fix

Ensure you are using Vite (not a custom bundler). Virtual modules are Vite-specific and won't work with plain Rollup.

affects: >=0.0.0

gotchaRTL support requires rtlcss to be installed as a dependency if runtimeIsRtlCondition is set

fix

Run `npm install --save-dev rtlcss` and set runtimeIsRtlCondition in plugin options.

affects: >=0.2.0

gotchaSSR build: virtual CSS modules are loaded as empty, so styles won't be injected server-side; client hydration will inject them, causing potential flash of unstyled content

fix

Ensure you have a ClientRouter or wait for hydration. Consider using a CSS-in-JS solution for SSR if flashes are unacceptable.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'vite-plugin-lazy-css-modules-inliner'

Package not installed or import path incorrect

fix

Install with `npm install --save-dev vite-plugin-lazy-css-modules-inliner` and verify package.json includes it.

TypeError: viteLazyCssInliner is not a function

Using default import instead of named import

fix

Change `import viteLazyCssInliner from ...` to `import { viteLazyCssInliner } from ...`.

Error: The plugin 'vite-plugin-lazy-css-modules-inliner' requires Vite >=4 but current version is 3.x

Incompatible Vite version

fix

Update Vite to version 4 or higher: `npm install vite@^4`.

Error: getModuleInfo(id).dynamicImporters is not a function

Using a Vite version older than 4 where getModuleInfo returns undefined

fix

Upgrade Vite to >=4, as the plugin relies on dynamicImporters property added in Vite 4.

Warning: You are using stripPreloadDepsMode: 'all' which may break chunk loading in some scenarios

Using a configuration option that is not recommended for general use

fix

Set stripPreloadDepsMode to 'css' (default) unless you have a specific reason to use 'all'.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

viterequiredPeer dependency: requires Vite >=4 for plugin hooks and build pipeline integration

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/DmitriiNazimov/vite-plugin-lazy-css-modules-inliner ↗

packagehttps://www.npmjs.com/package/vite-plugin-lazy-css-modules-inliner ↗