@finzor-ui/vite-plugin

@finzor-ui/vite-plugin

Плагин (и Nuxt-модуль), который подключает Finzor UI к Vite так, чтобы dev/SSR/first paint работали без ручной возни с optimizeDeps, ssr.noExternal и anti-FOUC для темы.

Стили компонентов Finzor не инжектит: они едут сами через module graph (import { FButton } from '@finzor-ui/button' → CSS чанка). Foundation по-прежнему один раз в приложении:

import '@finzor-ui/core/style.css'

Поддержка: Vite ^5 || ^6 || ^7 || ^8, пакеты @finzor-ui/* и @finzor-ui-pro/*.

Зачем он нужен

Без адаптера типичные сбои при работе с kit:

Когда можно обойтись без плагина: простой SPA, где вас устраивает дефолтный Vite, нет SSR и нет persist color-scheme. Стили компонентов всё равно приедут из module graph + core/style.css.

Когда ставить: Vite SSR, Nuxt, или SPA, где нужны prebundle, anti-FOUC тема или ранние предупреждения по зависимостям.

Модель доставки CSS / SSR

Контракт пакетов Finzor, на который опирается плагин:

• один изоморфный JS surface (dist/index.js) — нет dist/ssr.js и exports["."].node;
• CSS компонентов едет side-effect’ами из достигнутых public entry / chunks, не отдельными ./style.css / ./style-all.css;
• foundation — только import '@finzor-ui/core/style.css' в приложении;
• без package-closure inject и без prepend транзитивных CSS в index.js.

Эквивалент ручного SSR-конфига (если плагин не используете):

ssr: {
  noExternal: [/@finzor-ui(?:-pro)?\//]
}

Так Vite трансформирует пакеты и вытаскивает CSS side-effects на first paint.

Что плагин делает в проекте

Конкретно при plugins: [vue(), finzorUi(…)] (или Nuxt-модуле):

1. Сканирует исходники (src по умолчанию; в Nuxt — app, pages, components, …) на root-импорты @finzor-ui/* / @finzor-ui-pro/*.
2. Пишет optimizeDeps.include для найденных пакетов (+ @finzor-ui/core; в plain Vite по умолчанию ещё union с Finzor-deps из package.json). Tooling-only пакеты без module entry пропускает.
3. При ssr: true мержит в конфиг:

   ssr: { noExternal: [/@finzor-ui(?:-pro)?\//] }
   

   (идемпотентно; noExternal: true не трогает).
4. При theme / colorScheme — first-paint bootstrap на <html> (Vite: transformIndexHtml; Nuxt: app.head).
5. При validate: true (default) — warn, если пакет не резолвится, explicit-пакет не найден в scan, или один и тот же Finzor-пакет в dependencies и devDependencies с разными ranges.
6. При analyzeCss / debug — лог размеров dist/*.css по затронутым пакетам.

Чего плагин не делает:

• не подключает и не prepend’ит CSS-бандлы / style-all / package-closure;
• не требует отдельный @finzor-ui/*/ssr entry — один изоморфный JS;
• не заменяет import '@finzor-ui/core/style.css' в entry приложения.

Установка

pnpm add -D @finzor-ui/vite-plugin

Быстрый старт

Vite SPA

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { finzorUi } from '@finzor-ui/vite-plugin'

export default defineConfig({
  plugins: [vue(), finzorUi()]
})

// main.ts
import '@finzor-ui/core/style.css'
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

Vite SSR

import { finzorUi } from '@finzor-ui/vite-plugin'

export default defineConfig({
  plugins: [vue(), finzorUi({ ssr: true })]
  // noExternal для Finzor выставляет плагин
})

Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@finzor-ui/vite-plugin/nuxt'],
  // опционально:
  // finzorUi: { colorScheme: 'system', theme: 'corporate' }
})

Модуль сам включает ssr.noExternal, optimizeDeps (scan-first) и прокидывает те же опции в Vite-плагин. Foundation CSS — в entry / layout приложения, как в SPA.

Опции

Полные типы — в src/types.ts.

Anti-FOUC: тема и color scheme

Если пользователь может переключать светлую/тёмную схему (и тем более с persist), одного runtime FApp мало: до JS страница может мигнуть «не той» схемой.

Плагин при colorScheme:

1. Ставит на <html> data-color-scheme + compat class light|dark (для system в статике — fallback light).
2. Вставляет blocking script: читает localStorage['finzor-ui-color-scheme-preference'], иначе fallback из опции, резолвит system через matchMedia, пишет attr + class + style.colorScheme до paint.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@finzor-ui/vite-plugin/nuxt'],
  finzorUi: {
    colorScheme: 'system'
  }
})

<!-- runtime: FApp — writer; select без своего v-model на схему -->
<template>
  <FApp color-scheme="system" persist-color-scheme>
    <FColorSchemeSelect />
  </FApp>
</template>

finzorUi.colorMode (если подключён @nuxtjs/color-mode) — follower для $colorMode; DOM по-прежнему ведёт Finzor.

API

Корневой пакет также экспортирует низкоуровневые helpers (mergeFinzorSsrNoExternal, scan/optimize/bootstrap utils и т.д.) — для тестов и нестандартного wiring. В обычном приложении достаточно finzorUi или Nuxt-модуля.