Guida completa alla creazione di un ambiente di sviluppo per Gutenberg

Questa guida è per te che vuoi scrivere codice per Gutenberg con le sintassi ES6, ESNext e JSX e devi configurare webpack e babel per trasformarli in file che puoi usare nell’editor Gutenberg. Vedremo cosa devi fare, perché e come possiamo utilizzare ed estendere le impostazioni predefinite da WordPress e personalizzarle in base alle nostre esigenze.

Se sei nuovo di zecca ai concetti di npm, webpcak e Babel, dovresti leggere la sezione seguente che mira a spiegare le basi di come funzionano questi strumenti e come li usi. Tuttavia, se l’hai già fatto in precedenza e hai familiarità con il processo, magari sviluppando con React, passa alla sezione successiva in cui imposteremo effettivamente le cose.

Per principianti: npm, webpack e babel

Se non sei sicuro del motivo per cui dobbiamo fare tutto questo per scrivere Javascript per Gutenberg, ti consiglio di leggere il mio post che esplora le basi dello sviluppo per Gutenberg, dove spiego la differenza nelle versioni di Javascript e perché ne vale la pena.

Se non l’hai mai fatto prima, dovrai prima installare Node.js sul tuo computer. Fare clic sul collegamento, scaricarlo e installarlo. Incluso in Node.js otterrai uno strumento che utilizzeremo per impostare la maggior parte della configurazione. Questo strumento è npm, che consente di installare librerie Javascript ed eseguire script tramite riga di comando/terminale. Puoi in alternativa usare yarnse lo preferisci, ma per questa guida useremo npm.

npm

Questa guida non entrerà nel dettaglio di tutte le cose che puoi fare con npm, ma spiegherà il concetto di base e le cose che sono rilevanti per i nostri scopi. Useremo npmper due cose; per l’installazione delle librerie richieste nel nostro progetto e per l’esecuzione di comandi per creare (compilare) i nostri file Javascript.

Con npmpuoi installare qualsiasi pacchetto Javascript open source pubblico. Se dovessimo sviluppare con React (al di fuori di WordPress) avremmo bisogno di installare librerie React e librerie webpack. WordPress offre un’intera gamma di librerie (principalmente per Gutenberg) che puoi installare, ma a noi interessa solo una: @wordpress/scripts– che ci aiuta a semplificare la nostra configurazione.

Ogni volta che installi una libreria, npmverrà creata una sottocartella ” node_modules" in cui sono archiviate le librerie installate. Non dovrai mai entrare in questa cartella o modificare nulla qui, ma tieni presente che questa cartella conterrà facilmente (letteralmente!) decine di migliaia di file. Questa è una cartella che non dovresti mai impegnare a git o includere in alcun tema o plug-in finito. Le librerie sono necessarie solo durante lo sviluppo.

Quando il tuo ambiente è configurato, puoi usarlo npmper eseguire gli script definiti nel tuo package.jsonfile. A seconda del progetto normalmente avresti almeno due script; uno per creare gli script e uno per avviare la "modalità di visualizzazione". In "modalità orologio" npmavvia un processo nel terminale che attende e ascolta le modifiche apportate in qualsiasi file e le compila in fase di esecuzione ogni volta che premi Salva. Potresti avere familiarità con questo concetto se hai già utilizzato programmi di compilazione SCSS o LESS. È molto più efficiente eseguire uno script "watch" in background che si ricompila ogni volta che si salva, invece di andare al terminale ed eseguire il comando build dopo ogni modifica.

webpack e babel

Puoi ottenere sviluppando per Gutenberg senza eseguire alcun webpack o configurazione babel. Poiché utilizziamo le librerie di WordPress, lo gestiranno per noi. Tuttavia, questo ha uno svantaggio: l’impostazione predefinita è una posizione e un nome file fissi sia per i file di origine che per quelli di output. L’intero sviluppo di Javascript deve essere scritto all’interno di un file, in project-folder/src/index.js, e la build finirà sempre in project-folder/build/index.js. Se stai bene con questo, puoi saltare l’intera parte sulla configurazione del webpack. Tuttavia, se stai sviluppando un tema o un plug-in con diverse funzionalità di Gutenberg (blocchi personalizzati, filtri, ecc.), potresti almeno volere un nome e una posizione del file di output diversi, oltre a consentire più file.

Se utilizzi il pacchetto di WordPress per gestire l’installazione (@wordpress/scripts), Babel è già configurato. Ma dovresti essere consapevole del fatto che il pacchetto di WordPress potrebbe non includere plug-in che potresti voler utilizzare. C’è ad esempio un pacchetto che permette di utilizzare le nuove cosiddette “funzioni freccia" (myFunction = (param) => { }), per definire funzioni senza bisogno di associare this. Se vuoi assolutamente utilizzare queste funzionalità di ESNext, dovrai configurare tu stesso Babel invece di utilizzare le impostazioni predefinite di WordPress. Vedrò come di seguito.

Il processo

Il processo di sviluppo con webpack una volta che tutto è impostato e installato, consiste nel navigare nella cartella del progetto nel terminale e avviare lo script "watch". Rimarrà aperto e ascolterà le modifiche apportate ai tuoi file JS. Ogni volta che premi Salva nei tuoi file Javascript, il terminale emetterà informazioni (si spera) che ha ricompilato correttamente il file. Se si sono verificati errori di compilazione, verranno visualizzati nel terminale. Per interrompere il processo "guarda", premi CTRL + C.

Allestimento dell’ambiente

Presumo che tu abbia già un WordPress locale in esecuzione su alcuni stack LAMP (programmi come WampServer, XAMPP, Docker o simili) e che tu abbia un plugin o un tema pronto per iniziare a codificare il tuo Javascript.

Consiglio di creare una sottocartella dedicata allo sviluppo di Javascript poiché potresti ritrovarti con diversi file e cartelle di configurazione. Ciò semplifica la separazione dei file e delle cartelle (ad esempio node_modules/) che non si desidera includere nei commit git o nelle build finali. Ma va benissimo usare il tuo tema principale o la cartella del plugin come cartella del progetto per lo sviluppo di Javascript.

Nel terminale (il terminale Mac OS o il prompt dei comandi di Windows funzionano entrambi correttamente) vai alla cartella del progetto. Per quanto riguarda questo tutorial, presumo che siamo in un tema e abbiamo creato una sottocartella vuota gutenberg-dev/come cartella del nostro progetto.

Il primo passo è l’inizializzazione di un progetto npm, che in pratica è semplicemente dire npmdi generare un package.jsonfile. Questo package.jsonfile informa npmsu quali pacchetti sono richiesti e quali script sono disponibili per l’esecuzione. Digita questo nel terminale;

npm init -y

Questo genera un package.jsonfile con contenuto predefinito nella cartella del progetto.

Successivamente installeremo il pacchetto di WordPress che ci aiuterà a ridurre la quantità di configurazione che dovremo fare. Esegui questo comando:

npm install --save-dev --save-exact @wordpress/scripts

Il tag --save-devinforma npmche le librerie fornite sono necessarie solo per lo sviluppo e --save-exactsi assicura npmche installi solo una versione, l’ultima.

Apri il package.jsonfile nel tuo editor. (npmavrà anche generato un package-lock.jsonfile durante l’installazione dei pacchetti, puoi semplicemente ignorare questo file, package.jsonapporterai le modifiche). Dovrebbe essere riempito con la configurazione predefinita e potresti notare che l’installazione del pacchetto che abbiamo eseguito in precedenza ha aggiunto una voce @wordpress/scriptsdi una determinata versione in devDependencies. Man mano che installerai più pacchetti, npmverrà aggiornato package.jsoncon le voci per ogni pacchetto. Tutto ciò di cui dobbiamo preoccuparci in questo file è la scriptsproprietà, che è per gli script (comandi) che puoi usare npmper l’esecuzione. Aggiorna la proprietà degli script in questo (puoi rimuovere il "test" predefinito):

"scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
},

Questo pezzo di codice dice npmche abbiamo due script che possiamo eseguire in questa cartella del progetto; “costruisci” e “inizia”. Eseguiamo uno script con il comando npm run <scriptname>, in cui npmcercherà package.jsoned eseguirà il comando definito come suo valore. Usiamo lo strumento wp-scriptsfornito nel pacchetto che abbiamo appena installato per compilare il nostro Javascript una volta ("build") o avviare la modalità "guarda" / "ascolta" per compilare ogni volta che salviamo le modifiche ("start").

Questo ci consente anche di utilizzare il webpack di WordPress e la configurazione di Babel, quindi non dobbiamo farlo da soli.

Nella cartella del tuo progetto crea una sottocartella chiamata src/. All’interno di questa cartella crea un index.jsfile.

Se stai bene con le impostazioni predefinite del webpack, ora hai finito! index.jsScrivi il tuo codice ES6 e JSX e chiedi npmdi compilarli eseguendo il comando build:

npm run build

oppure avvia un processo "watch" nel terminale che ascolta le modifiche apportate con questo comando (usa CTRL+C per interrompere il processo di visualizzazione):

npm run start

L’esecuzione di uno di questi genererà una build/sottocartella nel tuo progetto direttamente con il risultato compilato in build/index.js.

Questo è tutto per la configurazione dell’ambiente più semplice! Ora sei pronto per scrivere Javascript ES6 per Gutenberg!

Se desideri modificare la posizione e i nomi dei file di origine o di output, continua a leggere.

Configurazione di nomi e percorsi di file di origine e di output

Se tu, come me, non sei soddisfatto del nome file e della struttura predefiniti, specialmente per i file di output, devi esaminare la configurazione del webpack. Normalmente, ad esempio, se stai sviluppando per React al di fuori di WordPress, dovresti impostare una configurazione completa del pacchetto web con il plug-in Babel. Fortunatamente WordPress si occupa di questo per noi e ci consente di estendere la configurazione del pacchetto web di WordPress e regolare solo le parti che vogliamo modificare.

Nella cartella del tuo progetto (la stessa cartella di package.json) crea un file chiamato webpack.config.jse aprilo nel tuo editor. Scrivi quanto segue in questo file:

const defaultConfig = require("@wordpress/scripts/config/webpack.config");
const path = require('path');
module.exports = {
    ...defaultConfig,
    entry: {
        'block-mynamespace-myblock': './src/block-mynamespace-myblock.js'
    },
    output: {
        path: path.join(__dirname, '../assets/js/gutenberg'),
        filename: '[name].js'
    }
}

La prima cosa che facciamo è recuperare @wordpress/scriptsla configurazione del webpack nella variabile defaultConfig. All’interno del webpack config module.exports, la prima cosa che facciamo è applicare tutto defaultConfigusando l’operatore spread (...). Queste due parti si stanno assicurando di estendere la configurazione del webpack di WordPress includendo tutto al suo interno. Dopo l’operatore di diffusione possiamo regolare o aggiungere qualsiasi proprietà che desideriamo modificare; nel nostro caso la posizione di origine e la posizione di output.

La entryproprietà definisce i file di origine, che per impostazione predefinita sono ./src/index.js. Ogni voce nella entryproprietà è una coppia chiave+valore da cui il webpack compilerà (e controllerà). Nell’esempio sopra ho definito ‘ block-mynamespace-myblock‘ che si trova in src/block-mynamespace-myblock.jsun punto di ingresso. Puoi aggiungere tutte le coppie chiave+valore qui per ogni file sorgente che desideri compilare.

La outputproprietà decide la posizione dei file compilati. In pathsi definisce la cartella di destinazione per tutti i file compilati. Sto usando un path helper per poter navigare correttamente nelle directory nella mia configurazione. Nell’esempio sopra sto dicendo al webpack che tutti i file compilati dovrebbero finire nella mia theme-folder/assets/js/gutenberg/cartella. La cosa importante è usare ../per attraversare l’albero delle directory, fuori dalla cartella del progetto e in un’altra cartella in cui voglio che siano tutti i file Javascript del mio tema. Regola il percorso per adattarlo alla struttura del tuo progetto.

In secondo luogo, sto dicendo al webpack che tutti i nomi di file dovrebbero essere nominati come i entrynomi delle chiavi corrispondenti. theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsQuesta configurazione del webpack compilerà il mio file theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Se dovessi aggiungere un altro file sorgente come coppia chiave+valore in entry, verrebbe compilato nella stessa cartella con la chiave come nome file.

Apporta le modifiche desiderate nel webpack.config.jsfile e salva. Eseguire nuovamente uno qualsiasi dei npmcomandi di compilazione per generare i file nelle nuove posizioni.

Questo è tutto! Ora hai esteso la configurazione del webpack di WordPress e ora controlli dove dovrebbero andare i tuoi file di origine e di output.

Tuttavia voglio includere un ultimo consiglio in questa guida. La configurazione predefinita di WordPress per Babel potrebbe non avere alcuni plug-in Babel per alcune nuove funzionalità in ESNext. Ad esempio, con l’impostazione predefinita sopra e le impostazioni predefinite di WordPress non sarai in grado di utilizzare le funzioni freccia nel tuo codice. Se questo è importante per te, continua a leggere.

Aggiungi il supporto per le più recenti sintassi ESNext con Babel

Al momento in cui scrivo, l’impostazione predefinita di Babel di WordPress manca del supporto per "sintassi sperimentali", che include ad esempio le funzioni delle frecce. Per aggiungere supporto per questo, devi fornire il tuo file di configurazione Babel, e finora non ho trovato un modo per estendere la configurazione Babel di WordPress come abbiamo fatto con la configurazione del webpack sopra. Quindi dobbiamo ridefinire i preset di Babel e aggiungere il plug-in "sintassi sperimentali". Ma non preoccuparti, è un file molto piccolo.

Il primo passo è installare alcuni pacchetti di cui abbiamo bisogno per i preset Babel: dobbiamo installare gli stessi definiti nella configurazione Babel di WordPress. Esegui questo comando per l’installazione @babel/preset-enve @babel/preset-react, così come il pacchetto che ci interessa; @babel/plugin-proposal-class-properties:

npm install --save-dev @babel/preset-env @babel/preset-react @babel/plugin-proposal-class-properties

Il secondo passaggio consiste nell’aggiungere il file di configurazione di Babel. Nella cartella del progetto, crea un file denominato .babelrc(nessuna estensione file).

Nota per Windows: se sei seduto su una macchina Windows non puoi creare file senza estensioni di file. Per aggirare questo problema, puoi creare questo file usando il terminale/prompt dei comandi. Esegui questo comando:

Questo comando genererà "ciao" nel file .babelrcnella cartella corrente. Ora puoi aprire questo file nel tuo editor, rimuovere il "ciao" e aggiungere il contenuto effettivo di seguito.

Il tuo .babelrcdovrebbe assomigliare a questo:

{
    "presets": ["@babel/preset-env", "@babel/preset-react"],
    "plugins": [
        [
            "@babel/plugin-proposal-class-properties"
        ]
    ]
}

Definiamo gli stessi preset che faresti normalmente in un progetto React, e lo stesso di WordPress. Quello che stiamo aggiungendo è la pluginsproprietà. All’interno dell’array pluginsaggiungiamo il @babel/plugin-proposal-class-propertiesplugin Babel necessario per "sintassi sperimentali" come le funzioni delle frecce.

Conclusione

Tieni presente che WordPress può modificare la sua configurazione in qualsiasi momento, è particolarmente probabile che ciò accada perché Gutenberg è abbastanza nuovo. Poiché estendiamo la configurazione di WordPress, a un certo punto potrebbe essere necessario aggiornare nuovamente la nostra configurazione per soddisfare le nostre esigenze. Forse WordPress decide di includere il supporto per sintassi sperimentali in modo da non dover eseguire l’intera configurazione di Babel.

Questa non è affatto una guida esauriente nella configurazione di Webpack e Babel, ma il risultato di un sacco di esperimenti e di capire le cose. Spero che questo ti abbia aiutato a imparare a configurare il tuo ambiente di sviluppo Gutenberg e lo abbia reso abbastanza semplice in modo che questo non sia un grosso ostacolo per iniziare a imparare ES6, ESNext, JSX e tutte quelle cose utili per lo sviluppo per Gutenberg!