Modifica di @david: Il sistema di temizzazione di Discourse ora supporta nativamente più file JS. Questo metodo webpack non è più necessario.
Ciao! Mentre stavo sviluppando il mio componente handsfree-discourse, ho incontrato alcuni problemi relativi alla gestione dei file. Il problema principale era la necessità di suddividere il mio codice in più file. L’altro problema era la necessità di includere librerie di terze parti senza dover chiedere agli amministratori di abilitare CORS o attivare ulteriori richieste HTTP.
Per risolvere questi problemi ho creato discourse-webpack, un boilerplate per impostare rapidamente componenti ricchi di JS! Le funzionalità includono:
- Server di sviluppo locale con ricaricamento automatico (live reloading)
- Include uno script di commit per mantenere il codice sorgente e il codice compilato in rami separati!
Il resto di questo argomento spiega come utilizzarlo e perché funziona. Ho appena finito di testarlo per alcuni altri componenti su cui sto lavorando, quindi fatecelo sapere se riscontrate problemi o se avete richieste specifiche!
Imposta rapidamente componenti JavaScript pesanti per la tua Community Discourse, completo di uno script di commit per mantenere il codice sorgente e il codice di build in rami separati per aiutarti a continuare a rilasciare velocemente!
Installazione
Assicurati prima di avere NodeJS >= 8 e git installati localmente sulla tua macchina. Quindi, digita ciascuna delle righe sottostanti:
# Scarica questo repository
git clone https://github.com/browsehandsfree/discourse-webpack
# Entra nella directory
cd discourse-webpack
# Installa le dipendenze
npm install
Dovrai quindi modificare quanto segue in package.json, sostituendo tutti i nostri link con i tuoi. Nello specifico:
{
name: 'your-project',
repository: {
url: 'git+https://github.com/username/repo'
},
author: '',
bugs: {
url: 'https://github.com/username/repo/issues'
},
homepage: 'https://example.com'
}
Soprattutto, assicurati che repository.url sia corretto e sia preceduto da git+. Quando esegui npm run discourse, verrà effettuato commit e push su quel repository.
Inoltre, non dimenticare di impostare il tuo about.json di Discourse, che si trova in /src/discourse/about.json.
Sviluppo
Dopo npm install, otterrai la seguente struttura di directory:
discourse-webpack
|- node_modules/ # Dipendenze
|- src/ # I principali file sorgente
|--|- discourse/ # File del tema Discourse
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css # Il foglio di stile principale
|--|- main.js # Il punto di ingresso Javascript principale
|--|- sandbox.html # Sandbox per lo sviluppo locale
|- .gitignore
|- discourse-push.js # Script di commit speciale
|- README.md
|- webpack.config.js # Configurazione Webpack
|- yarn.lock
Script da riga di comando
Inoltre, hai accesso ai seguenti comandi dalla root del progetto:
# Avvia un server di sviluppo su localhost:8080
# - Supporta il ricaricamento automatico (livereload)
# - Utilizza `/src/sandbox.html` per aiutarti a eseguire il debug localmente
npm run dev
# Compila il tuo componente in `/dist`
npm run build
# Compila il tuo componente in `/dist`
# - Quindi effettua il commit di `/dist` nel ramo `discourse`
npm run discourse
Come funziona
Una volta scaricato il repository e installate le dipendenze, è ora di iniziare a sviluppare! Usa npm run dev per avviare un server di ricaricamento automatico su localhost:8080.
Visitando quell’URL verrà caricato il file HTML situato in /src/sandbox.html. Questo file non viene effettivamente utilizzato all’interno di Discourse ed è presente solo per aiutarti a sviluppare i tuoi script localmente (al di fuori del contesto di Discourse).
Il punto di ingresso principale di webpack è /src/main.js. Da lì, puoi importare altri script e webpack raggrupperà tutto insieme e li inietterà nei seguenti file:
/src/sandbox.html/src/discourse/common/body_tag.html
main.js viene compilato e iniettato automaticamente in sandbox.html, ma viene iniettato manualmente in linea con body_tag.html a causa del seguente codice:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Se volessi iniettare il tuo script in un altro modello, come after_header.html, dovresti semplicemente copiare quel tag script in quel modello. Questo ti permette di mantenere separati l’HTML e il JavaScript per quel modello durante lo sviluppo… ma concatenati quando distribuiti!
Compilazione
Quando compili con npm run build, ecco cosa succede:
- Prima,
/src/main.jse le dipendenze vengono raggruppati - Poi, tutti i file in
/src/discourse/vengono copiati in/dist/ - Allo stesso tempo,
main.jsviene iniettato in linea in qualsiasi file di modello che contiene:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Distribuzione
Quando esegui npm run discourse, viene chiamato lo script /discourse-push.js che fa quanto segue:
- Prima compila, come se fosse con
npm run build - Poi, inizializza un nuovo repository git all’interno di
/dist - Infine, effettua il commit di
/distnel ramodiscoursedel tuo progetto (creerà il ramo se non esiste)
Utilizzo del ramo discourse
Ciascuno dei seguenti
/url/relativi/è relativo all’URL di base del tuo forum, ad esempio, https://example.com/url/relativi/
Installa il componente
Installa il tuo componente visitando /admin/customize/themes e scegliendo “Importa dal web” dal repository del tuo progetto, ad esempio: https://github.com/my-awesome/discourse-component.
Imposta quindi il ramo su discourse. Non funzionerà se lo lasci su master, poiché Discourse cercherà di caricare i file non compilati (se funziona affatto).
Debug dei file specifici del tema sul tuo host
- Installa il Discourse Theme CLI
- Accedi a https://theme-creator.discourse.org
- Esegui
cdin questa directory, quindi eseguidiscourse_theme watch . - Usa
https://theme-creator.discourse.orgcome URL di base- Usa la tua chiave API da
theme-creator
- Usa la tua chiave API da
Se sei nuovo in Discourse e vorresti fare un fork di questo progetto, le seguenti letture potrebbero essere utili.