Documentazione · src/plugin · src/cli · src/utils
Installare
Un plugin e un comando. Il pacchetto entra in un progetto da un punto solo, e ne esce lasciando file che appartengono al progetto.
Il plugin: un punto d’ingresso
Il plugin riceve la configurazione di Payload e la restituisce arricchita: collection, global, blocchi, hook, la vista dello Studio. È il solo punto in cui il pacchetto tocca la configurazione del progetto, e si può disabilitare — restituendo la configurazione intatta — il che serve più di quanto sembri quando si deve isolare un problema.
La collection media è opt-in: un progetto che ne ha già una non se ne vede imporre un’altra.
il plugin: cosa aggiunge alla configurazione
la media di default, opt-in
Cosa scaffolda `init`
npx woodylab-uims init scrive nel progetto i sei store (copiandoli dalle baseline), il file dei reducer app-state.ts, e i pezzi di configurazione che devono stare nel progetto perché il progetto li possa modificare.
In coda, se la collection utenti è vuota, crea il primo utente: ruolo ADMIN, credenziali fisse dette nell’esito (admin@uims.local / uims-admin), passando dal flusso ufficiale di Payload — la stessa operazione della schermata «create first user», auto-verifica inclusa. Mai in produzione, mai più dopo che un utente esiste, --no-first-user lo salta; se il database non è raggiungibile in quel momento lo dice e non blocca lo scaffold.
I template restano leggibili di proposito: sono sorgente destinato a essere modificato da chi installa, e minificarli sarebbe controproducente. Lo script di minificazione li salta esplicitamente.
Il comando è anche l’unica cosa che gate.sh esercita per intero: costruisce un progetto ex novo, installa il tarball, lancia init, compila. Un errore in init non si vede in nessun altro modo, perché in repo il progetto è già inizializzato.
il primo utente: flusso ufficiale, mai in prod, solo a collection vuota
lo scaffolding: store, reducer, configurazione, primo utente dev
Il comando
npx woodylab-uims init
Cosa lascia nel progetto
db.viewmodes.json db.styles.json db.base-vars.json db.themes.json db.animations.json db.events.json .claude/skills/uims/SKILL.md // da qui in poi sono tuoi: nessun aggiornamento del pacchetto li riscrive
Il pacchetto non spedisce migrazioni
Le trasformazioni del contenuto già scritto appartengono a chi possiede quel contenuto: sono funzioni pure da dato a dato, e dipendono da come quel progetto ha usato i blocchi. Il pacchetto non può scriverle al posto tuo senza fare assunzioni su dati che non ha mai visto.
Chi installa oggi non ha niente da migrare: parte dalla forma corrente. Spedirle significava pubblicare la nostra cronologia interna come superficie pubblica, e con essa l’impegno a mantenerla — perché togliere un sottopercorso, dopo, è un cambiamento che rompe.
Resta vero il problema che risolvevano, e riguarda te: cambiare la forma di un tuo blocco non tocca il contenuto già scritto. Quella trasformazione è del progetto, ed è una funzione pura da dato a dato — a leggere e scrivere ci pensa uno script tuo. Vedi la pagina Estendere.
I servizi
Cinque file che non appartengono a nessuna delle aree precedenti e servono a più di una: le CSS var che il generatore scrive in .uims/, la cache dei global, la conversione dei colori, il catalogo delle icone.
le variabili del tema attivo, come CSS var
Da uno stile nominato a una regola
generateStyleRules([{ name: 'elevationMd', css: 'box-shadow: 0 10px 30px -12px rgba(0,0,0,.35);' }])
// '.us-elevationMd { box-shadow: 0 10px 30px -12px rgba(0,0,0,.35); }'Da dove arrivano le variabili
generateCssVars(settings, styles, vars) // base ⊕ palette del tema ⊕ override: l'ultima scrittura vince, // e cio che nessuno nomina resta il valore di base
la lettura in cache di un global
la conversione per le var colore con opacità
il catalogo delle icone disponibili