vite-plugin-lazy-css-modules-inliner

Note: A Russian version of this README is available below.

A Vite plugin that enables true on-demand CSS for dynamically imported code by virtualizing CSS Modules. It prevents lazy components' styles from being bundled into the page CSS and injects them only when the corresponding JS is actually used.

Installation

npm i vite-plugin-lazy-css-modules-inliner --save-dev

Example of usages see in section Examples.

Supported stacks

• Vite (vanilla)
• CSS-modules
• Astro + Vite
• React / Vue / Svelte — when styles are imported as external *.module.css

Limitations: native SFC styles (<style> inside .svelte/.vue) are out of scope.

Goals

• Keep page (synchronous) CSS clean from lazy modules' styles
• Load lazy JS + CSS together on demand
• Preserve CSS Modules hashing consistency between SSR and client
• Avoid preloading page CSS/JS from __vitePreload in dynamic chunks

How it works (build pipeline and runtime)

1. Detect dynamic roots
   • SSR: resolveDynamicImport marks import() targets as roots
   • Client: transform uses getModuleInfo(id).dynamicImporters and also promotes dynamicallyImportedIds as roots
2. Propagate laziness
   • resolveId treats children of lazy importers as part of the lazy graph
   • CSS imports inside the lazy graph are rerouted to virtual JS modules
3. Virtual CSS modules
   • SSR load: returns an empty module — styles are not collected into the page CSS bundle
   • Client load:
     • reads CSS, applies postcss-modules if needed, minifies with cssnano in prod
     • generates a virtual JS module that imports a shared runtime (lazy-css-inliner:runtime) and either:
       • plain CSS: calls ensureLazyCssInjected(id, css) immediately
       • CSS Modules: exports a Proxy that injects CSS only on the first token access
4. Strip CSS deps from __vitePreload
   • renderChunk filters out .css entries when stripPreloadDepsMode: 'css' (or all deps when 'all')

Note about bundling: virtual CSS code can still end up inside a shared parent chunk depending on Rollup splitting. This does not inject styles early — injection happens only when the virtual module executes (or when CSS‑Module tokens are accessed). If you want stricter chunk boundaries, add simple manualChunks rules in your Vite config.

Options

export type StripPreloadDepsMode = 'all' | 'css';

export interface PluginOptions {
    stripPreloadDepsMode?: StripPreloadDepsMode; // default: 'css'
    isDev?: boolean; // dev switch (sourcemaps/minify)
    includedPathes?: string[]; // roots to include; default: [path.join(root,'src')]
    excludedPathes?: string[]; // paths to exclude; default: ['node_modules']
    runtimeIsRtlCondition?: string; // optional JS condition evaluated at runtime to enable RTL (e.g. 'window.isRtl')
}

Defaults are applied at configResolved when not provided.

RTL support

If runtimeIsRtlCondition is provided, the plugin enables RTL mode:

• Duplicates client chunks under rtl/ and keeps all imports relative so nested dynamic imports resolve within rtl/.
• Converts inlined CSS to RTL during duplication using rtlcss lib.
• Appends .rtl to lazy CSS ids to avoid collisions.
• Filters __vitePreload deps at runtime so only the appropriate (LTR/RTL) JS and CSS are requested.

Diagnostics

• Mixed static + dynamic imports of the same module can duplicate CSS by design. Prefer picking one strategy or accept the trade‑off.
• Above‑the‑fold dynamic modules will inject CSS very early — consider static import instead.
• If virtual CSS appears in a shared parent chunk, consider build.rollupOptions.output.manualChunks to separate domains (dialogs, overlays, etc.).

Examples

• vite.config.ts

import { defineConfig } from 'vite';
import { viteLazyCssInliner } from 'vite-plugin-lazy-css-modules-inliner';
import path from 'node:path';

export default defineConfig({
    plugins: [
        viteLazyCssInliner({
            includedPathes: [path.join(process.cwd(), 'src')],
            excludedPathes: ['node_modules'],
            stripPreloadDepsMode: 'css', // or 'all' to disable all __vitePreload deps
            isDev: process.env.NODE_ENV === 'development',
            runtimeIsRtlCondition: 'window.isRtl',
        }),
    ],
});

vite-plugin-lazy-css-modules-inliner (Русская версия)

Плагин Vite, виртуализирующий CSS Modules для динамически импортируемого кода. Стили ленивых модулей не попадают в общий CSS страницы и инжектятся только при фактическом использовании соответствующего кода.

Установка

npm i vite-plugin-lazy-css-modules-inliner --save-dev

Примеры использования см. в секции Examples.

Поддержка

• Vite (vanilla)
• Astro + Vite
• React / Vue / Svelte — при подключении *.module.css

Ограничения: встроенные стили SFC (<style> внутри .svelte/.vue) вне зоны ответственности.

Цели

• Держать страничный CSS чистым от стилей ленивых модулей
• Грузить JS+CSS по требованию
• Сохранять консистентность хэшей CSS Modules между SSR и клиентом
• Удалять .css из __vitePreload в динамических чанках

Как работает (пайплайн и рантайм)

Ниже — краткая «дорожная карта» того, что делает плагин на разных стадиях:

1. Находим «ленивые корни» (dynamic roots)

   • На SSR: хук resolveDynamicImport перехватывает import() и помечает цель импорта как корень ленивого подграфа.
   • На клиентской сборке: хук transform анализирует getModuleInfo(id) и:
     • если у модуля есть dynamicImporters — он является целью чьего‑то import() → тоже корень;
     • дополнительно продвигает dynamicallyImportedIds в корни (дети по динамическим рёбрам).

2. Распространяем «ленивость» вниз по зависимостям

   • В resolveId если импортёр уже внутри ленивого подграфа, то все его дочерние зависимости становятся «ленивыми» тоже.
   • Для CSS внутри такого подграфа мы не отдаём обычный CSS‑модуль; вместо этого возвращаем виртуальный JS‑модуль (см. п.3).
   • Для не‑CSS ничего не ломаем: возвращаем исходный resolvedModule.id (сохраняются query вида ?url, ?raw).

3. Генерируем виртуальные CSS‑модули

   • На SSR: load() возвращает пустой модуль, чтобы стили не попали в общий CSS страницы.
   • На клиенте: load() читает исходный .css, при необходимости применяет postcss-modules (получаем tokens), минимизирует в проде и генерирует JS‑модуль, который:
     • импортирует общий рантайм из lazy-css-inliner:runtime;
     • если это обычный CSS — сразу вызывает ensureLazyCssInjected(id, css) (синхронная вставка <style data-lazy-css-id="..."> в <head>);
     • если это CSS Modules — экспортирует Proxy над tokens; инъекция выполняется один раз при первом обращении к любому токену.

4. Контролируем прелоад зависимостей

   • В renderChunk можно удалять .css из массива зависимостей __vitePreload (режим 'css') либо вычищать все deps (режим 'all'). Это помогает избежать преждевременных подгрузок.

Важно про чанки: виртуальный код CSS может оказаться внутри «родительского» чанка в результате сплиттинга Rollup. Это не приводит к ранней инъекции — вставка стилей происходит только в момент выполнения виртуального модуля (или при первом доступе к токенам CSS Modules). Если нужно жёстко развести домены, используйте build.rollupOptions.output.manualChunks.

Опции

export interface PluginOptions {
    stripPreloadDepsMode?: 'css' | 'all'; // по умолчанию 'css'
    isDev?: boolean; // dev‑режим
    includedPathes?: string[]; // директории для обработки; по умолчанию [root/src]
    excludedPathes?: string[]; // исключения; по умолчанию ['node_modules']
    runtimeIsRtlCondition?: string; // опционально: JS‑условие, включающее RTL в рантайме (например, 'window.isRtl')
}

Значения по умолчанию подставляются в configResolved, если опции не заданы.

Поддержка RTL

Если задана runtimeIsRtlCondition, плагин включает RTL‑режим:

• Дублирует клиентские чанки в подпапку rtl/, сохраняя относительные импорты — вложенные динамические импорты автоматически резолвятся внутри rtl/.
• Преобразует инлайн‑CSS в RTL при дублировании через rtlcss.
• Добавляет суффикс .rtl к lazy CSS id, чтобы избежать коллизий.
• Фильтрует зависимости __vitePreload так, чтобы в рантайме запрашивались корректные (LTR/RTL) JS и CSS.

Диагностика

• Смешение статического и динамического импорта одного и того же модуля может привести к дублям CSS — это ожидаемо. Лучше выбрать один подход.
• Для блоков «над сгибом» лучше статический импорт — динамика инжектит CSS позднее.
• Если виртуальный CSS попадает в общий чанк — настройте manualChunks (например, разнести диалоги, оверлеи по отдельным чанкам).

Примеры

См. секцию выше для vite/astro конфигураций.