cic-kit

cic-kit e un kit di componenti, store e utility per Vue 3, pensato per progetti web con Bootstrap, Firebase e workflow PWA.

Il pacchetto espone:

• componenti UI riusabili
• plugin CicKit per registrazione globale dei componenti
• utility per Firebase/Auth/Firestore
• gestione toast, toolbar, header, local storage, form validator
• helper PWA/push notifications (RegisterSW, AutoPushPermissionModal, pushMsg)

Indice

1. Requisiti
2. Installazione
3. Integrazione base
4. Stili
5. PWA e notifiche push
6. API pushMsg (FCM)
7. Variabili ambiente demo/esempio
8. Sviluppo locale della demo
9. Build
10. Documentazione componenti
11. Troubleshooting
12. Changelog

Requisiti

• Node.js 20+ consigliato
• npm 10+ consigliato
• progetto host su Vue 3 + Vite

Il progetto host deve avere le peerDependencies richieste da cic-kit. Installazione rapida:

npm install vue vue-router bootstrap firebase vee-validate @vee-validate/yup yup @tiptap/core @tiptap/starter-kit @tiptap/vue-3 @tiptap/extension-heading @tiptap/extension-link @tiptap/extension-code-block @tiptap/extension-placeholder

Installazione

Installa il pacchetto:

npm install cic-kit

Integrazione base

Esempio tipico in main.ts:

import { createApp } from "vue";
import App from "./App.vue";
import { router } from "./router";
import {
  CicKit,
  _CurrentUser,
  cicKitStore,
  initAuth,
  setupFirebase,
  type FirebaseConfig,
} from "cic-kit";

import "bootstrap/dist/css/bootstrap.min.css";
import "cic-kit/style.css";

const firebaseConfig: FirebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY ?? "",
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN ?? "",
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID ?? "",
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET ?? "",
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID ?? "",
  appId: import.meta.env.VITE_FIREBASE_APP_ID ?? "",
  measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID ?? undefined,
  databaseURL: import.meta.env.VITE_FIREBASE_DATABASE_URL ?? undefined,
  functionsRegion: import.meta.env.VITE_FIREBASE_FUNCTIONS_REGION ?? "europe-west1",
};

cicKitStore.isDev = import.meta.env.VITE_USE_FIREBASE_EMULATORS === "true";
setupFirebase(firebaseConfig);

const Auth = initAuth(_CurrentUser);
Auth.checkAuth();

const app = createApp(App);
app.use(router);
app.use(CicKit);
app.mount("#app");

Stili

Hai due opzioni:

• CSS pronto:

import "cic-kit/style.css";

• SCSS:

@use "bootstrap/scss/bootstrap";
@use "cic-kit/style";

Nota: se usi SCSS, importa Bootstrap prima di cic-kit/style. Nota: cic-kit non include Bootstrap internamente, Bootstrap deve essere installato e importato dal progetto host.

PWA e notifiche push

Se usi il componente RegisterSW o l'import virtuale virtual:pwa-register, devi configurare vite-plugin-pwa.

1) Installa il plugin (obbligatorio per PWA)

npm install vite-plugin-pwa -D

2) Configura vite.config.ts

Esempio con injectManifest:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { VitePWA } from "vite-plugin-pwa";

export default defineConfig({
  plugins: [
    vue(),
    VitePWA({
      strategies: "injectManifest",
      srcDir: "src",
      filename: "sw.ts",
      injectRegister: false,
      registerType: "autoUpdate",
      manifest: false,
      devOptions: { enabled: true },
    }),
  ],
});

3) Tipi TypeScript (consigliato)

In src/vite-env.d.ts (o equivalente):

/// <reference types="vite/client" />
/// <reference types="vite-plugin-pwa/client" />

4) Usa RegisterSW e configura VAPID

Nel tuo root component:

<script setup lang="ts">
import { RegisterSW, AutoPushPermissionModal, pushMsg } from "cic-kit";
import { registerSW } from "virtual:pwa-register";

pushMsg.vapidPublicKey = import.meta.env.VITE_FIREBASE_VAPID_PUBLIC_KEY ?? "";
</script>

<template>
  <RegisterSW :registerSW="registerSW" />
  <AutoPushPermissionModal :only-after-login="true" />
</template>

RegisterSW salva la ServiceWorkerRegistration in cicKitStore.ServiceWorkerReg, necessaria per i flussi FCM del device.

API pushMsg (FCM)

API principale disponibile da cic-kit:

• pushMsg.askPermission()
• pushMsg.getCurrentFcmToken()
• pushMsg.registerFcmToken()
• pushMsg.isThisDeviceTokenRegistered()
• pushMsg.removeThisDeviceToken()
• pushMsg.send(...) (notifica locale)
• pushMsg.sendTo(uid, ...) (invio remoto via callable function sendUserPush)
• AutoPushPermissionModal (modal auto per spiegare richiesta permesso notifiche)

Sono esportate anche come funzioni named:

import {
  getCurrentFcmToken,
  registerFcmToken,
  isThisDeviceTokenRegistered,
  removeThisDeviceToken,
} from "cic-kit";

Esempio completo:

import { pushMsg } from "cic-kit";

pushMsg.vapidPublicKey = import.meta.env.VITE_FIREBASE_VAPID_PUBLIC_KEY ?? "";

await pushMsg.askPermission();
const token = await pushMsg.registerFcmToken();
const registered = await pushMsg.isThisDeviceTokenRegistered();
console.log({ token, registered });

Comportamento lato utente autenticato

registerFcmToken() e removeThisDeviceToken() usano _Auth?.user.

• se non sei loggato, il token puo essere ottenuto ma non viene salvato nel profilo utente
• se sei loggato, il token viene sincronizzato su user.fcmTokens

Variabili ambiente demo/esempio

Template disponibile in demo/.env.example:

VITE_USE_FIREBASE_EMULATORS=false
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=
VITE_FIREBASE_MEASUREMENT_ID=
VITE_FIREBASE_DATABASE_URL=
VITE_FIREBASE_FUNCTIONS_REGION=europe-west1
VITE_FIREBASE_VAPID_PUBLIC_KEY=

Sviluppo locale della demo

1. Crea il file env locale:

Copy-Item demo/.env.example demo/.env.local

2. Compila i valori Firebase in demo/.env.local.
3. Avvia la demo:

npm run start

Altri comandi utili:

• npm run build:demo
• npm run preview:demo

Build

• build libreria + tipi:

npm run build

• build solo dichiarazioni:

npm run build:types

Documentazione componenti

Documentazione locale:

• docs/Btn.md
• docs/FieldTiptap.md
• docs/LS.md
• docs/Modal.md
• docs/pushMsg.md
• docs/toast.md

Troubleshooting

TS2307: Cannot find module virtual:pwa-register

Cause comune:

• vite-plugin-pwa non installato/configurato
• tipi PWA mancanti in vite-env.d.ts

Checklist:

1. Installa il plugin:

npm install vite-plugin-pwa -D

2. Configura VitePWA(...) in vite.config.ts.
3. Aggiungi:

/// <reference types="vite-plugin-pwa/client" />

ServiceWorker non registrato

cicKitStore.ServiceWorkerReg non e valorizzato. Monta <RegisterSW :register-s-w="registerSW" /> (o registra manualmente il SW e assegna la registration a cicKitStore.ServiceWorkerReg).

VAPID_PUBLIC_KEY mancante

Imposta pushMsg.vapidPublicKey con VITE_FIREBASE_VAPID_PUBLIC_KEY.

Firebase non inizializzato

Chiama setupFirebase(firebaseConfig) prima di usare API push/Firebase.

Changelog

• CHANGELOG.md