Abbiamo migrato i nostri tre progetti frontend da Parcel a Vite, e il processo è stato... fluido.
Abbiamo tre principali progetti frontend in Logto: l'esperienza di accesso, la Console e l'anteprima live. Questi progetti sono tutti in TypeScript, React, e moduli SASS; in totale, contano circa 100K linee di codice.
Abbiamo amato Parcel per la sua semplicità e la configurazione zero. Ricordo ancora il giorno in cui rimasi sbalordito da quanto fosse facile configurare un nuovo progetto con Parcel. Puoi semplicemente eseguire parcel index.html e boom, tutte le dipendenze necessarie vengono installate e il progetto è in esecuzione. Se sei un sviluppatore "esperto", potresti provare la stessa sensazione paragonandolo ai vecchi tempi dell'impostazione con Gulp e Webpack. Parcel è come una bacchetta magica.
La semplicità di Parcel è stata la ragione principale per cui siamo rimasti con lui per così tanto tempo, anche se a volte può essere capriccioso. Ad esempio:
Allora perché abbiamo deciso di migrare a qualcos'altro?
Qualcuno ha persino aperto una discussione per chiedere se Parcel è morto. La risposta ufficiale è no, Parcel è ancora vivo, ma è in uno stato di stiamo-lavorando-su-una-grande-rifattorizzazione-e-non-c'è-tempo-per-le-rilasci-minori. Per noi, è come una "morte dell'anatra": l'ultima versione che possiamo usare risale a più di un anno fa, e non sappiamo quando sarà rilasciata la prossima versione. Sembra che sia morto, si comporta come se fosse morto, quindi per noi è morto.
Conoscevamo Vite da Vitest. Alcuni mesi fa, ci siamo stancati del supporto ESM di Jest (nei test) e volevamo provare qualcosa di nuovo. Vitest ci ha conquistato con il supporto nativo a ESM e la compatibilità con Jest. Ha un'esperienza per sviluppatori fantastica, ed è alimentato da Vite.
Potresti avere impostazioni diverse nel tuo progetto, ma di solito troverai sostituzioni di plugin poiché l'ecosistema Vite è in piena espansione. Ecco le nostre configurazioni al momento della migrazione:
Abbiamo iniziato la migrazione creando un nuovo progetto Vite e sperimentandolo per vedere come funziona. Il processo è stato fluido e la migrazione effettiva ha richiesto solo pochi giorni.
Vite offre supporto pronto all'uso per monorepo, ESM, TypeScript, React e SASS. Abbiamo solo dovuto installare i plugin necessari e le configurazioni per farlo funzionare.
Vite ha il supporto integrato per gli alias di percorso, ad esempio, nel nostro tsconfig.json:
Abbiamo solo dovuto aggiungere la stessa risoluzione nel nostro vite.config.ts:
Nota che il percorso di sostituzione dovrebbe essere un percorso assoluto, mentre è relativo alla radice del progetto. In alternativa, puoi utilizzare il plugin vite-tsconfig-paths per leggere gli alias di percorso dal tsconfig.json.
Sebbene Vite abbia il supporto integrato per HMR, è necessario installare un plugin per abilitare React Fast Refresh. Abbiamo usato il plugin @vitejs/plugin-react fornito dal team di Vite, che offre un ottimo supporto per le funzionalità di React come Fast Refresh:
Utilizziamo il plugin vite-plugin-svgr per convertire SVG in componenti React. È semplice come aggiungere il plugin alla configurazione di Vite:
Tuttavia, non abbiamo specificato in base a quale condizione gli SVG dovrebbero essere convertiti in componenti React, quindi tutte le importazioni sono state convertite. Il plugin offre una configurazione predefinita migliore: convertire solo gli SVG che sono stati importati con l'estensione .svg?react. Abbiamo aggiornato di conseguenza le nostre importazioni.
Sebbene Vite abbia il supporto integrato per i moduli SASS, c'è una cosa di cui dobbiamo occuparci: come i nomi delle classi sono formattati. Potrebbe essere problematico per gli utenti e per i nostri test di integrazione se i nomi delle classi non sono formattati in modo coerente. La configurazione in una riga nel vite.config.ts può risolvere il problema:
A proposito, Parcel e Vite hanno diversi modi di importare i file SASS:
La sintassi * as, tuttavia, funziona in Vite, ma causerà la perdita di nomi di classe modularizzati quando si utilizzano chiavi dinamiche per accedere all'oggetto styles. Ad esempio:
Poiché Vite utilizza Rollup sotto il cofano, possiamo utilizzare il plugin ufficiale @mdx-js/rollup per supportare MDX e i suoi plugin. La configurazione è la seguente:
Il plugin remarkGfm è utilizzato per supportare Markdown in stile GitHub e il plugin rehypeMdxCodeProps è utilizzato per passare le proprietà ai blocchi di codice nei file MDX come fa Docusaurus.
Vorremmo utilizzare diagrammi Mermaid nei nostri file MDX come se fossero altri linguaggi di programmazione. L'uso dovrebbe essere semplice come altri blocchi di codice:
Dovrebbe essere reso come:
%3btext-align:center%3b%7d%23mermaid-0 .edgeLabel p%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 .edgeLabel rect%7bopacity:0.5%3bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bfill:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 .labelBkg%7bbackground-color:rgba(232%2c 232%2c 232%2c 0.5)%3b%7d%23mermaid-0 .cluster rect%7bfill:%23ffffde%3bstroke:%23aaaa33%3bstroke-width:1px%3b%7d%23mermaid-0 .cluster text%7bfill:%23333%3b%7d%23mermaid-0 .cluster span%7bcolor:%23333%3b%7d%23mermaid-0 div.mermaidTooltip%7bposition:absolute%3btext-align:center%3bmax-width:200px%3bpadding:2px%3bfont-family:arial%2csans-serif%3bfont-size:12px%3bbackground:hsl(80%2c 100%25%2c 96.2745098039%25)%3bborder:1px solid %23aaaa33%3bborder-radius:2px%3bpointer-events:none%3bz-index:100%3b%7d%23mermaid-0 .flowchartTitleText%7btext-anchor:middle%3bfont-size:18px%3bfill:%23333%3b%7d%23mermaid-0 rect.text%7bfill:none%3bstroke-width:0%3b%7d%23mermaid-0 .icon-shape%2c%23mermaid-0 .image-shape%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3btext-align:center%3b%7d%23mermaid-0 .icon-shape p%2c%23mermaid-0 .image-shape p%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bpadding:2px%3b%7d%23mermaid-0 .icon-shape rect%2c%23mermaid-0 .image-shape rect%7bopacity:0.5%3bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bfill:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 :root%7b--mermaid-font-family:arial%2csans-serif%3b%7d%3c/style%3e%3cg%3e%3cmarker orient='auto' markerHeight='8' markerWidth='8' markerUnits='userSpaceOnUse' refY='5' refX='5' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-pointEnd'%3e%3cpath style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 0 0 L 10 5 L 0 10 z'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='8' markerWidth='8' markerUnits='userSpaceOnUse' refY='5' refX='4.5' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-pointStart'%3e%3cpath style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 0 5 L 10 10 L 10 0 z'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5' refX='11' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-circleEnd'%3e%3ccircle style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' r='5' cy='5' cx='5'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5' refX='-1' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-circleStart'%3e%3ccircle style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' r='5' cy='5' cx='5'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5.2' refX='12' viewBox='0 0 11 11' class='marker cross flowchart-v2' id='mermaid-0_flowchart-v2-crossEnd'%3e%3cpath style='stroke-width: 2%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 1%2c1 l 9%2c9 M 10%2c1 l -9%2c9'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5.2' refX='-1' viewBox='0 0 11 11' class='marker cross flowchart-v2' id='mermaid-0_flowchart-v2-crossStart'%3e%3cpath style='stroke-width: 2%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 1%2c1 l 9%2c9 M 10%2c1 l -9%2c9'/%3e%3c/marker%3e%3cg class='root'%3e%3cg class='clusters'/%3e%3cg class='edgePaths'%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_A_B_0' d='M72.451%2c62L67.598%2c66.167C62.746%2c70.333%2c53.041%2c78.667%2c48.188%2c86.333C43.336%2c94%2c43.336%2c101%2c43.336%2c104.5L43.336%2c108'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_A_C_1' d='M135.338%2c62L140.191%2c66.167C145.043%2c70.333%2c154.748%2c78.667%2c159.601%2c86.333C164.453%2c94%2c164.453%2c101%2c164.453%2c104.5L164.453%2c108'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_B_D_2' d='M43.336%2c166L43.336%2c170.167C43.336%2c174.333%2c43.336%2c182.667%2c47.683%2c190.566C52.029%2c198.465%2c60.723%2c205.929%2c65.069%2c209.662L69.416%2c213.394'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_C_D_3' d='M164.453%2c166L164.453%2c170.167C164.453%2c174.333%2c164.453%2c182.667%2c160.106%2c190.566C155.76%2c198.465%2c147.066%2c205.929%2c142.72%2c209.662L138.373%2c213.394'/%3e%3c/g%3e%3cg class='edgeLabels'%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3c/g%3e%3cg class='nodes'%3e%3cg transform='translate(103.89453125%2c 35)' id='flowchart-A-0' class='node default'%3e%3crect height='54' width='70.671875' y='-27' x='-35.3359375' style='' class='basic label-container'/%3e%3cg transform='translate(-5.3359375%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='10.671875'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eA%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(43.3359375%2c 139)' id='flowchart-B-1' class='node default'%3e%3crect height='54' width='70.671875' y='-27' x='-35.3359375' style='' class='basic label-container'/%3e%3cg transform='translate(-5.3359375%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='10.671875'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eB%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(164.453125%2c 139)' id='flowchart-C-3' class='node default'%3e%3crect height='54' width='71.5625' y='-27' x='-35.78125' style='' class='basic label-container'/%3e%3cg transform='translate(-5.78125%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='11.5625'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eC%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(103.89453125%2c 243)' id='flowchart-D-5' class='node default'%3e%3crect height='54' width='71.5625' y='-27' x='-35.78125' style='' class='basic label-container'/%3e%3cg transform='translate(-5.78125%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='11.5625'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eD%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/svg%3e)
Poiché la nostra app supporta temi chiari e scuri, abbiamo scritto un po' di codice per far funzionare i diagrammi Mermaid con il tema scuro. È stato creato un componente React:
useTheme è un hook personalizzato per ottenere il tema corrente dal contesto. La libreria mermaid è importata in modo asincrono per ridurre le dimensioni di caricamento della pagina iniziale.
Per il blocco di codice nel file MDX, abbiamo un componente unificato per svolgere il lavoro:
Infine, definiamo il provider MDX come segue:
Questa non è una cosa specifica di Vite, vale comunque la pena menzionarla dato che abbiamo aggiornato le nostre pagine per utilizzare il caricamento lazy durante la migrazione, e nulla si è rotto successivamente.
React ha una funzione integrata React.lazy per caricare in modo lazy i componenti. Tuttavia, potrebbe causare alcuni problemi quando stai iterando velocemente. Abbiamo creato una piccola libreria chiamata react-safe-lazy per risolvere i problemi. È un sostituto drop-in per React.lazy e una spiegazione dettagliata può essere trovata in questo post sul blog.
C'è un plugin carino chiamato vite-plugin-compression per produrre asset compressi. Supporta sia la compressione gzip che brotli. La configurazione è semplice:
Una grande funzionalità di Vite (o dell'underlying Rollup) è i chunk manuali. Mentre React.lazy viene utilizzato per il caricamento lazy dei componenti, possiamo avere un maggiore controllo sui chunk specificando i chunk manuali per decidere quali componenti o moduli dovrebbero essere raggruppati insieme.
Ad esempio, possiamo prima usare vite-bundle-visualizer per analizzare la dimensione del bundle e le dipendenze. Poi possiamo scrivere una funzione appropriata per dividere i chunk:
A differenza della build di produzione, Vite NON raggrupperà il tuo codice sorgente in modalità sviluppo (inclusi dipendenze collegate nello stesso monorepo) e tratterà ogni modulo come un file. Per noi, il browser caricherà centinaia di moduli per la prima volta, il che sembra pazzesco ma in realtà va bene nella maggior parte dei casi. Puoi vedere la discussione qui.
Se è un problema per te, una soluzione alternativa ma non perfetta è elencare le dipendenze collegate nell'opzione optimizeDeps del vite.config.ts:
Ciò "pre-bundle" le dipendenze collegate e rende il server di sviluppo più veloce. Il problema è che HMR potrebbe non funzionare come previsto per le dipendenze collegate.
Inoltre, utilizziamo un proxy che serve i file statici in produzione e instrada le richieste al server Vitest in fase di sviluppo. Abbiamo configurato alcune porte specifiche per evitare conflitti, ed è anche facile configurarlo nel vite.config.ts:
A differenza di Parcel, Vite utilizza un approccio moderno per gestire le variabili d'ambiente utilizzando import.meta.env. Caricherà automaticamente i file .env e sostituirà le variabili nel codice. Tuttavia, richiede che tutte le variabili d'ambiente siano prefissate con VITE_ (configurabile).
Mentre utilizzavamo Parcel, semplicemente sostituiva le variabili process.env senza controllare il prefisso. Quindi abbiamo trovato una soluzione temporanea utilizzando il campo define per facilitare la migrazione:
Questo ci consente di aggiungere gradualmente il prefisso alle variabili d'ambiente e rimuovere il campo define.
Ecco fatto! Abbiamo migrato con successo i nostri tre progetti frontend da Parcel a Vite e speriamo che questa breve storia possa aiutarti nella tua migrazione. Ecco come appare la configurazione alla fine: