Salta al contenuto principale
Versione: 5.x

Plugin del Tema

Cos'è un plugin del tema?​

Verdaccio, di default, utilizza un'UI personalizzata che fornisce una buona serie di funzonalità per visualizzare i pacchetti ma, il tuo team, potrebbe necessitare di delle funzionalità aggiuntive e personalizzate, ed è qui che un tema personalizzato diventa un'opzione. Il plugin memorizza delle risorse statiche, che saranno caricate dal lato del client, alla visualizzazione della pagina.

Come funziona la fase di caricamento di un plugin del tema?​

Come caricano le risorsee del tema?​

attenzione

Di default, l'applicazione carica su http://localhost:4873, ma nei casi in cui un proxy inverso con dominio personalizzato è coinvolto, le risorse sono caricate secondo la proprietà __VERDACCIO_BASENAME_UI_OPTIONS.base e __VERDACCIO_BASENAME_UI_OPTIONS.basename, dunque, soltanto una configurazione del dominio è utilizzabile.

Il tema carica soltanto dal lato del client, l'applicazione renderizza HTML con i tag <script> per visualizzarla, il bundler si occupa del caricamento di qualsiasi altra risorsa, come svg, images o chunk associati con essa.

L'oggetto __VERDACCIO_BASENAME_UI_OPTIONS​

window.__VERDACCIO_BASENAME_UI_OPTIONS è disponibile nel contesto globale del browser, la forma è documentta e definita qui alle definizioni dei tipi di TemplateUIOptions.

// esempio di output
{
    "darkMode": false,
    "basename": "/",
    "base": "https://registry.my.org/",
    "primaryColor": "#4b5e40",
    "version": "5.20.1",
    "pkgManagers": [
        "yarn",
        "pnpm",
        "npm"
    ],
    "login": true,
    "logo": "",
    "title": "Verdaccio Registry",
    "scope": "",
    "language": "es-US"
}

Configurazione del Tema​

Di default, Verdaccio carica @verdaccio/ui-theme, impacchettato nel pacchetto principale, se desideri caricare il tuo plugin personalizzato, dev'essere installato laddove sia individuabile.


$> npm install --global verdaccio-theme-dark

attenzione

Il prefisso del nome del plugin deve iniziare per verdaccio-theme-xxx, altrimenti, il plugin sarà ignorato. :::caution

Puoi caricare soltanto un tema per volta (se ne sono forniti di più, il primo viene selezionato) e passare le opzioni, se necessario.

theme:
  dark:
    option1: foo
    option2: bar

Queste opzioni saranno disponibili

Struttura del plugin​

Se disponi di un tema dell'interfaccia utente personalizzato, deve seguire una struttura specifica:

{
  "name": "verdaccio-theme-xxxx",
  "version": "1.0.0",
  "description": "my custom user interface",
  "main": "index.js",
}

Il file principale index.js dovrebbe contenere i seguenti contenuti.

module.exports = () => {
  return {
    // posizione dei file statici, output del pacchetto web
    staticPath: path.join(__dirname, 'static'),
    // file json del manifesto del pacchetto web
    manifest: require('./static/manifest.json'),
    // file manifest principali da caricare
    manifestFiles: {
      js: ['runtime.js', 'vendors.js', 'main.js'],
    },
  };
};

Se una delle seguenti proprietà non è disponibile, il plugin non caricherà, dunque, segui questa struttura.

  • staticPath: è la posizione assoluta/relativa dei file statici, potrebbe essere qualsiasi percorso con require.resolve o da te creato; ciò che è importante si trova nel pacchetto o in qualsiasi posizione che il middleware Express.js possa trovare; dietro le quinte è utilzzato res.sendFile.
  • manifest: L'oggetto del manifesto di un pacchetto web.
  • manifestFiles: Un oggetto con una proprietà js e l'insieme (l'ordine conta) dell'ID del manifesto da caricare dinamicamente nel modello.
  • manifestFiles si riferisce ai file principali che devono essere caricati come parte degli script html, per poter caricare la pagina; non devi includere i chunk, essendo caricati dinamicamente dal bundler.

File del manifesto​

Verdacco richiede a un oggetto manifesto di renderizzare dinamicamente HTML, insieme a manifestFiles, l'applicazione comprende cosa renderizzare.

Correntemente, supporta soltanto js ma, se necessiti anche di css, siamo aperti a discuterne e a fornire ulteriori miglioramenti.

const { WebpackManifestPlugin } = require('webpack-manifest-plugin');

  plugins: [
    ...
    new WebpackManifestPlugin({
      // facoltativo, dipende dalla tua implementazione
      removeKeyHash: true,
    }),
    ...
  ],

Manifesto con altri bundler​

Non esiste alcun feedback con altri bundler utilizzati con i plugin del tema, ma con esbuild potrebbe essere possibile generare manifesti.

Alternative:

Componenti dell'UI​

I componenti dell'UI sono una funzionalità sperimentale utilizzabile da verdaccio@5.x, aperta alle modifiche e ai feedback.

nota

Creare una nuova interfaccia utente da zero è un grande sforzo, ma per facilitare il compito, esiste il pacchetto @verdaccio/ui-components. I componenti si basano sulla libreria React e Material UI.

Il pacchetto esporta parte dell'interfaccia dell'utente che potrebbe essere riutilizzata:

  • Hook di React
  • Fornitori (API di React Context)
  • Componenti
  • Sezioni: (Barra laterale, Dettaglio, Intestazione, Pagina Home e Piè di Pagina)

https://ui-components.verdaccio.org