Getting Started

ConfigPlugin

Configurazione icone e localizzazione con ConfigPlugin di @pzeta/vue-components.

Cos'è il ConfigPlugin

ConfigPlugin è il plugin Vue responsabile della configurazione globale delle icone in @pzeta/vue-components. Usa il meccanismo provide/inject di Vue per rendere la configurazione reattiva e disponibile in tutti i componenti discendenti.

Con ConfigPlugin puoi sostituire il set di icone predefinito (PrimeIcons) con Lucide Icons, FontAwesome o qualsiasi icon set personalizzato, senza modificare i componenti.

::: note La localizzazione (testi e label dei componenti) è gestita da @pzeta/vue-i18n tramite la funzione configureI18n(), separata da ConfigPlugin. Le due configurazioni sono indipendenti.

@pzeta/vue-i18n non esporta un plugin Vue: la configurazione è una semplice chiamata di funzione (singleton globale), non un app.use(...). :::

Import CSS obbligatorio — @pzeta/vue-components/style.css DEVE essere importato nell'entry dell'app (main.ts o mfe-entry.ts). Senza questo import i componenti vengono renderizzati senza i loro stili (tema, spacing, varianti severity, layout interno di DataTable, Dialog, Drawer, ecc.) e l'app sembra "rotta" anche se la logica è corretta.

import '@pzeta/vue-components/style.css' // ← MAI dimenticare

:::

Configurazione icone

Registrazione base

import { createApp } from 'vue'
import App from './App.vue'
import { ConfigPlugin } from '@pzeta/vue-components'

const app = createApp(App)
app.use(ConfigPlugin)
app.mount('#app')

Senza opzioni, ConfigPlugin usa defaultIcons (PrimeIcons).

Preset disponibili

La libreria include tre preset pronti all'uso:

Preset	Import	Icon set
`defaultIcons`	`import { defaultIcons } from '@pzeta/vue-components'`	PrimeIcons (`pi pi-*`)
`lucideIcons`	`import { lucideIcons } from '@pzeta/vue-components'`	Lucide Static (`icon-*`)
`fontAwesomeIcons`	`import { fontAwesomeIcons } from '@pzeta/vue-components'`	FontAwesome 7 (`fa-solid fa-*`)

Usare Lucide Icons

import { createApp } from 'vue'
import App from './App.vue'
import { ConfigPlugin, lucideIcons } from '@pzeta/vue-components'

const app = createApp(App)
app.use(ConfigPlugin, { icons: lucideIcons })
app.mount('#app')

Installa anche il pacchetto dei font Lucide nel tuo progetto:

npm install lucide-static

E importa il CSS delle icone nel tuo main.ts o main.css:

import 'lucide-static/font/lucide.css'

Usare FontAwesome

import { ConfigPlugin, fontAwesomeIcons } from '@pzeta/vue-components'

app.use(ConfigPlugin, { icons: fontAwesomeIcons })

npm install @fortawesome/fontawesome-free

import '@fortawesome/fontawesome-free/css/all.min.css'

Override parziale

Puoi sovrascrivere solo alcune icone mantenendo il preset di base:

import { ConfigPlugin, lucideIcons } from '@pzeta/vue-components'

app.use(ConfigPlugin, {
  icons: {
    ...lucideIcons,
    common: {
      ...lucideIcons.common,
      close: 'fa-solid fa-xmark', // override singolo
    },
  },
})

Icone custom (icon set proprietario)

Puoi usare qualsiasi icon set definendo un oggetto ComponentIcons completo:

import type { ComponentIcons } from '@pzeta/vue-components'

const myIcons: ComponentIcons = {
  common: {
    close: 'my-icon-close',
    loading: 'my-icon-spinner spin',
    clear: 'my-icon-clear',
    check: 'my-icon-check',
    minus: 'my-icon-minus',
    search: 'my-icon-search',
  },
  // ... tutte le altre categorie
}

app.use(ConfigPlugin, { icons: myIcons })

Categorie icone disponibili

Categoria	Descrizione
`common`	Icone generiche (close, loading, check, search)
`table`	Ordinamento, espansione righe, stato vuoto
`paginator`	Navigazione pagine (prima, precedente, successiva, ultima)
`form`	Dropdown, password, upload, calendario, rating
`overlay`	Dialog, drawer (chiudi, massimizza)
`navigation`	Menu, submenu, scroll-to-top
`severity`	Success, info, warn, error, secondary, contrast
`button`	Loading, dropdown SpeedDial
`list`	OrderList e PickList (sposta su/giù/in cima/in fondo)
`image`	Anteprima e chiusura viewer immagini
`weather`	WeatherCard (sole, nuvole, pioggia, temporale)

Aggiornamento icone a runtime

Tramite il composable useIcons() puoi aggiornare la configurazione icone in modo reattivo anche dopo il mount dell'applicazione:

<script setup lang="ts">
import { useIcons } from '@pzeta/vue-components'

const { config } = useIcons()

function switchToLucide() {
  import('@pzeta/vue-components').then(({ lucideIcons }) => {
    config.setIcons(lucideIcons)
  })
}
</script>

Configurazione localizzazione

La localizzazione è gestita da @pzeta/vue-i18n tramite la funzione configureI18n() (singleton globale, non un plugin Vue). La libreria include traduzioni per 5 lingue.

::: note Il dizionario italiano it è già esportato dalla libreria @pzeta/vue-components: non riscriverlo a mano nel consumer. Importa direttamente it da @pzeta/vue-components e passalo come preloaded. Le altre lingue si caricano lazy on-demand via loadEn(), loadFr(), ecc. :::

Export reali di `@pzeta/vue-i18n`

Export	Tipo	Uso
`configureI18n(config)`	funzione	Inizializza il singleton i18n. Chiamare una sola volta prima di `createApp(...).mount()`.
`isI18nConfigured()`	funzione	Ritorna `true` se il singleton è già stato configurato (utile in monorepo / MFE per evitare doppia init).
`getI18nConfig()`	funzione	Restituisce la config corrente.
`useI18n()`	composable	Accesso reattivo a `t()`, `setLocale()`, `addMessages()`, ecc. dentro componenti.
`loadLocale(key)` / `isLocaleLoaded(key)`	funzione	Caricamento on-demand di una locale registrata.
`initI18n()` / `resetI18n()` / `resetI18nFull()`	funzione	Hook per test / dev.

Non esiste I18nPlugin. Pattern tipo app.use(I18nPlugin, { messages: { it } }) non funziona — @pzeta/vue-i18n non espone un plugin Vue. Usare configureI18n({...}).

Lingue disponibili

Lingua	Codice	Caricamento
Italiano	`it`	Precaricato (incluso nel bundle, esportato come `it` da `@pzeta/vue-components`)
Inglese	`en`	Lazy-loaded (`loadEn()`)
Francese	`fr`	Lazy-loaded (`loadFr()`)
Spagnolo	`es`	Lazy-loaded (`loadEs()`)
Tedesco	`de`	Lazy-loaded (`loadDe()`)

Setup con lingua italiana

import { createApp } from 'vue'
import App from './App.vue'
import '@pzeta/vue-components/style.css'
import { PzetaComponents, ConfigPlugin, lucideIcons, it } from '@pzeta/vue-components'
import {
  configureI18n,
  isI18nConfigured,
  type TranslationDictionary,
} from '@pzeta/vue-i18n'

// Configura i18n PRIMA di creare l'app.
// Cast `it` (ComponentLocale) → TranslationDictionary: compatibili a runtime
// ma definiti in pacchetti separati senza dipendenza tipi reciproca.
if (!isI18nConfigured()) {
  const itDict = it as unknown as TranslationDictionary
  configureI18n({
    defaultLocale: 'it',
    fallbackLocale: 'it',
    locales: {
      it: {
        loader: () => Promise.resolve({ default: itDict }),
        preloaded: itDict,
      },
    },
  })
}

const app = createApp(App)

app.use(ConfigPlugin, { icons: lucideIcons })
app.use(PzetaComponents)

app.mount('#app')

::: note La guard isI18nConfigured() evita la doppia inizializzazione del singleton — fondamentale in monorepo / microfrontend dove più moduli possono importare @pzeta/vue-i18n e tentare di configurarlo. :::

Cambio lingua a runtime

import { createApp } from 'vue'
import App from './App.vue'
import '@pzeta/vue-components/style.css'
import { PzetaComponents, ConfigPlugin, it } from '@pzeta/vue-components'
import { configureI18n, isI18nConfigured, type TranslationDictionary } from '@pzeta/vue-i18n'

if (!isI18nConfigured()) {
  const itDict = it as unknown as TranslationDictionary
  configureI18n({
    defaultLocale: 'it',
    fallbackLocale: 'it',
    locales: {
      it: { loader: () => Promise.resolve({ default: itDict }), preloaded: itDict },
    },
  })
}

const app = createApp(App)
app.use(ConfigPlugin)
app.use(PzetaComponents)
app.mount('#app')

<script setup lang="ts">
import { useI18n } from '@pzeta/vue-i18n'
import { loadEn, loadFr } from '@pzeta/vue-components'

const { setLocale, addMessages } = useI18n()

async function switchToEnglish() {
  const { default: en } = await loadEn()
  addMessages('en', en)
  setLocale('en')
}

async function switchToFrench() {
  const { default: fr } = await loadFr()
  addMessages('fr', fr)
  setLocale('fr')
}
</script>

Esempio completo setup main.ts

import { createApp } from 'vue'
import App from './App.vue'

// CSS — l'import di `@pzeta/vue-components/style.css` è OBBLIGATORIO.
import '@pzeta/vue-components/style.css'
import 'lucide-static/font/lucide.css'

import {
  PzetaComponents,
  ConfigPlugin,
  lucideIcons,
  it,
} from '@pzeta/vue-components'
import {
  configureI18n,
  isI18nConfigured,
  type TranslationDictionary,
} from '@pzeta/vue-i18n'

// 1. i18n — configurazione singleton PRIMA di createApp.
if (!isI18nConfigured()) {
  const itDict = it as unknown as TranslationDictionary
  configureI18n({
    defaultLocale: 'it',
    fallbackLocale: 'it',
    locales: {
      it: { loader: () => Promise.resolve({ default: itDict }), preloaded: itDict },
    },
  })
}

const app = createApp(App)

// 2. Icone Lucide
app.use(ConfigPlugin, { icons: lucideIcons })

// 3. Tutti i componenti
app.use(PzetaComponents)

app.mount('#app')

Configurazione

Modalità di configurazione di @pzeta/vue-components — plugin globale, selettivo, named imports.

Setup Tailwind

Integrazione di @pzeta/vue-components con Tailwind CSS 4.