Установка

Быстрый старт даёт один рабочий путь без объяснений. Эта страница объясняет: почему состав зависимостей именно такой, что из него попадает в бандл, а что живёт только на сборке.

Требования

@feugene/fint-i18n — peer тоже, но помеченный необязательным: без него компоненты говорят по-английски встроенными строками, а не падают. Подробности — на странице локализации.

Единственный поддерживаемый способ

Подключение идёт через @feugene/granum — конвейер, который читает манифест пакета и собирает из него один лист. Прямые импорты CSS-файлов и подключение styles.css в обход конвейера не поддерживаются — они работают ровно до первого обновления и ломаются молча. Компонент из корня пакета granum не пропустит вовсе: это ошибка сборки ComponentRootImportError, компоненты берут из подпутей.

Манифест — не соглашение об именах файлов, а объявленный экспорт: @feugene/granularity/granum.manifest.json. Поэтому granum не сканирует node_modules и не угадывает раскладку пакета: такого канала у него нет вовсе.

Исключение названо в самом пакете: @feugene/granularity/styles.css — готовый лист с токенами, базовым слоем, preflight и обеими темами для тех, кто конвейер не запускает вовсе. Его части экспортированы и по отдельности — @feugene/granularity/styles/* (tokens.css, base.css, preflight.css, themes/light.css, themes/dark.css) — для того же случая. Ни то ни другое не даёт утилитарных классов, которыми нарисованы шаблоны компонентов.

Что и куда

# в dependencies — попадает в приложение
yarn add vue @feugene/granularity @floating-ui/dom @unocss/reset

# в devDependencies — исполняется только на сборке
yarn add -D @feugene/granum @feugene/granum-engine-wind

@feugene/granularity — в dependencies: его компоненты импортируются из исходников приложения и попадают в бандл.

@floating-ui/dom — в dependencies приложения, а не внутрь пакета. На нём построено позиционирование всех выпадающих панелей — GrSelect, GrAutocomplete, GrTreeSelect, GrDropdown, GrDropdownMenu, GrContextMenu, GrTooltip, GrPopover, GrColorPicker — и, через них, GrPagination, GrDataTable и GrSidebar. Пакет держит библиотеку внешней и не бандлит внутрь dist — иначе приложение, которое само использует floating-ui, получило бы вторую копию.

@feugene/granum и движок — в devDependencies: они исполняются на сборке и ни одной строкой не попадают в бандл. У обоих ноль зависимостей: словарь preset-wind3 вендорен внутрь движка, и ставить unocss не нужно — его в дереве не будет вовсе.

@unocss/reset — в dependencies, как в быстром старте ядра: его лист попадает в CSS приложения — одной строкой @import из вашего CSS, а не импортом из кода.

Наращивание конфига

Минимальный рабочий конфиг — движок, провайдер и папка с исходниками:

import { windEngine } from '@feugene/granum-engine-wind'
import { defineGranumConfig } from '@feugene/granum/vite'

export default defineGranumConfig({
  engine: windEngine(),
  providers: ['@feugene/granularity'],
  appSources: { dirs: ['src'] },
})

import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import { granum } from '@feugene/granum/vite'
import granumConfig from './granum.config.mjs'

export default defineConfig({
  plugins: [Vue(), granum(granumConfig)],
})

Он уже подмешивает токены, базовый слой и тему light, включает все компоненты провайдера с их стилями и поднимает правила, варианты и safelist. Дальше опциями сужают и уточняют:

Отдельной опции «где искать классы в node_modules» нет и не нужно: классы компонентов приезжают из манифеста пакета, уже посчитанными на его сборке. У пресета v1 это было ручной строкой content.filesystem, и утилита, встречающаяся только внутри лениво загружаемого острова, до листа не доезжала.

Иконки

Свои иконки пакет привозит с собой. Стрелка селекта, крестик очистки, галочка выбранной опции, спиннер, ручка переноса компилируются в dist при сборке пакета. Ставить unplugin-icons или коллекцию ради них не нужно.

Своя иконка приходит двумя способами. Пропы icon принимают либо Vue-компонент, либо класс:

<script setup lang="ts">
import { ref } from 'vue'
import { GrTabs } from '@feugene/granularity/components/GrTabs'
import IconUser from '~icons/lucide/user'

const tab = ref('a')
</script>

<template>
  <GrTabs v-model="tab" :tabs="[{ value: 'a', label: 'Profile', icon: IconUser }]" />
  <GrTabs v-model="tab" :tabs="[{ value: 'a', label: 'Profile', icon: 'i-lucide-user' }]" />
</template>

Первая строка передаёт компонент — откуда он, пакету всё равно. Здесь он приходит из unplugin-icons, и этот плагин вместе с коллекцией @iconify-json/lucide ставит и настраивает приложение. Вторая передаёт класс: CSS для него генерирует ваш конфиг, а не пакет.

yarn add -D @iconify-json/lucide

Правило пишет приложение — ни granum, ни движок готового не везут — и отдаёт его фабрике движка:

import { windEngine } from '@feugene/granum-engine-wind'

export default defineGranumConfig({
  engine: windEngine({ rules: [iconRule] }),
  providers: ['@feugene/granularity'],
})

Два импорта CSS, и порядок между ними несущий

Лист вставляет не интеграция, а приложение: в точке входа его импортируют руками.

import './reset.css'
import 'virtual:granum.css'

@import '@unocss/reset/tailwind-compat.css' layer(reset);

Сброс уезжает в свой слой, и это не оформление. granum отдаёт всё своё в слои granum.*, а нелейерный CSS бьёт ЛЮБОЙ @layer независимо от специфичности: вне слоя button { color: inherit } из сброса перебил бы утилиты компонента, и кнопка приехала бы с цветом текста страницы.

Слой обязан объявиться раньше слоёв granum — место слоя в каскаде задаёт его первое появление, — поэтому reset.css импортируется первым. Перепутанный порядок не даёт ни ошибки, ни предупреждения: сборка проходит, ломается только картинка.

Опциональные интеграции

• @feugene/unplugin-granularity — резолвер для unplugin-vue-components: авто-импорт компонентов и директив в шаблонах. Вставляет статические импорты в SFC, поэтому tree-shaking остаётся идеальным.
• createGranularity из @feugene/granularity/vue — runtime-адаптер для директив в render/JSX, общего provide и globalProperties. Сам он не импортирует ни одного компонента: что передадите, то и зарегистрируется.

Оба дополняют основной способ установки, а не заменяют его. Настройка обоих — в конфигурации.