@finzor-ui/vite-plugin

v0.5.12

Published

13 days ago

Vite plugin for Finzor UI: optimizeDeps, SSR noExternal, theme bootstrap, and Nuxt module.

0High
0Medium
0Low

@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:

| Симптом | Причина | Что делает плагин | | -------- | ------- | ----------------- | | Медленный / нестабильный cold start в dev | Vite не знает, какие Finzor-пакеты prebundle’ить | Сканирует импорты приложения и пишет optimizeDeps.include | | В SSR/Nuxt нет стилей Finzor на first paint | Vite считает пакеты external и не достаёт CSS side-effects | При ssr: true (и в Nuxt-модуле) мержит ssr.noExternal для Finzor scopes | | Мигание светлой/тёмной темы до гидрации | <html> ещё без data-color-scheme / class | Опционально выставляет attrs + blocking script до paint | | Тихие ошибки «пакет не резолвится» / конфликт версий | Забыли установить / разные ranges в deps и devDeps | Warn-only проверки на старте сборки |

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

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

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

| Режим | CSS | |-------|-----| | SPA | Module graph (достигнутые entry/chunks) + @finzor-ui/core/style.css | | Vite SSR / Nuxt | то же + ssr.noExternal для scopes @finzor-ui/* / @finzor-ui-pro/* |

Контракт пакетов 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-модуле):

Сканирует исходники (src по умолчанию; в Nuxt — app, pages, components, …) на root-импорты @finzor-ui/* / @finzor-ui-pro/*.
Пишет optimizeDeps.include для найденных пакетов (+ @finzor-ui/core; в plain Vite по умолчанию ещё union с Finzor-deps из package.json). Tooling-only пакеты без module entry пропускает.
При ssr: true мержит в конфиг:
```
ssr: { noExternal: [/@finzor-ui(?:-pro)?\//] }
```
(идемпотентно; noExternal: true не трогает).
При theme / colorScheme — first-paint bootstrap на <html> (Vite: transformIndexHtml; Nuxt: app.head).
При validate: true (default) — warn, если пакет не резолвится, explicit-пакет не найден в scan, или один и тот же Finzor-пакет в dependencies и devDependencies с разными ranges.
При 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.

Опции

| Option | Default | Для пользователя | |--------|---------|------------------| | ssr | false | Включите для Vite SSR. В Nuxt-модуле включается автоматически. | | theme | — | Значение data-theme на <html> до первого paint. | | colorScheme | — | 'light' \| 'dark' \| 'system' — anti-FOUC для цветовой схемы. | | scanDirs | ['src'] / Nuxt dirs | Куда смотреть static-импорты Finzor. | | includePackageJsonDeps | true (Vite) / false (Nuxt) | Добавлять Finzor из package.json в optimizeDeps roots. | | validate | true | Warn-only проверки зависимостей. | | analyzeCss / debug | false | Диагностика CSS/roots в консоли. | | packages | 'auto' | Явный список пакетов для validate/analyze. | | colorMode | false | Только Nuxt: opt-in sync с @nuxtjs/color-mode (Finzor = DOM driver). | | messages | false | Только Nuxt: глобальные defaults для @finzor-ui/messages через setConfig. |

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

Anti-FOUC: тема и color scheme

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

Плагин при colorScheme:

Ставит на <html> data-color-scheme + compat class light|dark (для system в статике — fallback light).
Вставляет 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

| Import | Когда | | ------ | ----- | | finzorUi из @finzor-ui/vite-plugin | Vite / Vite SSR | | default / module из @finzor-ui/vite-plugin/nuxt | Nuxt (configKey: 'finzorUi') |

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@finzor-ui/vite-plugin

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

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

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

Установка

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

Vite SPA

Vite SSR

Nuxt

Опции

Anti-FOUC: тема и color scheme

API