Installation

Getting started gives you one working path with no explanations. This page explains: why the dependency list looks the way it does, what of it reaches the bundle and what only ever runs at build time.

Requirements

@feugene/fint-i18n is a peer too, but an optional one: without it the components speak English through their built-in strings rather than failing. Details are on the localization page.

The one supported way

Everything goes through @feugene/granum — the pipeline that reads the package manifest and assembles a single sheet from it. Importing CSS files directly and pulling in styles.css around the pipeline are not supported — they work right up to the first upgrade and then break silently. A component from the package root does not get through granum at all: it is a ComponentRootImportError build error, and components come from their subpaths.

The manifest is not a file-naming convention but a declared export: @feugene/granularity/granum.manifest.json. That is why granum never scans node_modules and never guesses a package’s layout: it has no such channel at all.

The exception is named by the package itself: @feugene/granularity/styles.css is a ready-made sheet with the tokens, the base layer, the preflight and both themes, for consumers who do not run the pipeline at all. Its parts are also exported one by one — @feugene/granularity/styles/* (tokens.css, base.css, preflight.css, themes/light.css, themes/dark.css) — for the same case. Neither gives you the utility classes the component templates are drawn with.

What goes where

# in dependencies — it ends up inside the application
yarn add vue @feugene/granularity @floating-ui/dom @unocss/reset

# in devDependencies — it only ever runs at build time
yarn add -D @feugene/granum @feugene/granum-engine-wind

@feugene/granularity goes into dependencies: its components are imported from your sources and land in the bundle.

@floating-ui/dom goes into the application’s dependencies, not inside the package. It positions every floating panel — GrSelect, GrAutocomplete, GrTreeSelect, GrDropdown, GrDropdownMenu, GrContextMenu, GrTooltip, GrPopover, GrColorPicker — and, through them, GrPagination, GrDataTable and GrSidebar. The package keeps the library external and does not bundle it into dist — otherwise an application that already uses floating-ui would end up with a second copy.

@feugene/granum and the engine go into devDependencies: they run at build time and not a single line of them reaches the bundle. Both have zero dependencies: the preset-wind3 vocabulary is vendored inside the engine, so there is no need to install unocss — it will not be in your tree at all.

@unocss/reset goes into dependencies, as in the core’s own getting started: its sheet ends up in the application’s CSS — through a single @import line in your CSS rather than an import from code.

Growing the config

The minimal working config is the engine, the provider and your source folder:

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)],
})

That already mixes in the tokens, the base layer and the light theme, enables every component of the provider with its styles, and brings up the rules, variants and safelist. From there you narrow and refine with options:

There is no “where to look for classes inside node_modules” option, and none is needed: a component’s classes arrive from the package manifest, already counted when the package was built. In the v1 preset this was a hand-written content.filesystem line, and a utility that only ever appeared inside a lazily loaded island never reached the sheet.

Icons

The package brings its own icons with it. The select arrow, the clear cross, the check mark on the chosen option, the spinner and the drag handle are compiled into dist when the package is built. You do not need unplugin-icons or an icon collection for them.

Your own icon arrives in one of two ways. The icon props take either a Vue component or a class:

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

The first line passes a component, and the package does not care where it comes from — here it comes from unplugin-icons, which the application installs and configures together with the @iconify-json/lucide collection. The second passes a class: the CSS for it is generated by your config, not by the package.

yarn add -D @iconify-json/lucide

The application writes the rule itself — neither granum nor the engine ships one — and hands it to the engine factory:

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

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

Two CSS imports, and the order between them is load-bearing

The sheet is not injected by an integration — your application imports it by hand at the entry point.

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

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

The reset goes into its own layer, and that is not decoration. granum puts everything of its own into granum.* layers, and unlayered CSS beats ANY @layer regardless of specificity: outside a layer, button { color: inherit } from the reset would override the component’s own utilities, and the button would arrive in the page’s text colour.

The layer must be declared before granum’s — a layer’s place in the cascade is fixed by its first appearance — which is why reset.css is imported first. Getting the order wrong produces neither an error nor a warning: the build passes, only the picture breaks.

Optional integrations

• @feugene/unplugin-granularity — a resolver for unplugin-vue-components: auto-import of components and directives in templates. It inserts static imports into the SFC, so tree-shaking stays as tight as it was.
• createGranularity from @feugene/granularity/vue — a runtime adapter for directives used in render/JSX, for a shared provide and for globalProperties. It imports no components itself: what you pass is what gets registered.

Both complement the main way of installing rather than replacing it. Setting up either one is covered in configuration.