====== Node.js ======
**[[https://nodejs.org/en|Node.js]]** is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.
===== Installazione del tool npm =====
apt install npm
...
0 upgraded, 390 newly installed, 0 to remove and 0 not upgraded.
Need to get 26.8 MB of archives.
After this operation, 165 MB of additional disk space will be used.
Do you want to continue? [Y/n]
===== Inizializzazione di un pacchetto =====
npm create ol-app openlayers-test
Need to install the following packages:
create-ol-app@1.2.0
Ok to proceed? (y) y
Il comando **create** è un alias di **init** (vedi ''man npm-init''). In questo caso **ol-app** è l'//initializer//. Questo potrebbe essere installato localmente come pacchetto **create-ol-app**, altrimenti viene scaricato automaticamente dal **registry** pubblico. È possibile specificare una specifica versione dell'initializer con sintassi del tipo **ol-app@latest** oppure **ol-app@1.2.0**.
Per cercare gli initializer disponibili sul //registry// si usa il comando **npm search**:
npm search ol-app
NAME | DESCRIPTION | AUTHOR | DATE | VERSION | KEYWORDS
create-ol-app | Initialize a new… | =tschaub | 2024-11-01 | 1.2.0 | openlayers ol map mapping
...
===== Il registry (repository) =====
Per sapere quale //registry// si sta utilizzando:
npm config ls -l | grep '^registry ='
registry = "https://registry.npmjs.org/"
Per avere informazioni più dettagliate su un intializer (ad esempio conoscere l'URL per scaricarlo dal registry):
npm view create-ol-app
...
dist
.tarball: https://registry.npmjs.org/create-ol-app/-/create-ol-app-1.2.0.tgz
...
===== Spazio di lavoro =====
L'initializer viene salvato localmente in una directory del tipo **$HOME/.npm/_npx/[hash_id]/node_modules/create-ol-app/**. Il pacchetto invece viene installato nella directory specificata poiché in questo caso è l'initializer stesso (os-app) che prende il primo parametro come directory destinazione.
Lo specifico progetto **create-ol-app** scarica tutte le dipendenze occupando circa 42 Mb:
du -sh openlayers-test/
42M openlayers-test/
===== Esecuzione in ambiente test =====
È possibile eseguire il progetto in un ambiente di test con il comando **npm start**:
cd openlayers-test/
npm start
Questo specifico progetto utilizza il tool **Vite** (scaricato come dipendenza) per offrire un server web locale:
VITE v6.2.2 ready in 315 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
===== Preparazione per il deploy =====
Con il comando **npm run build** si genera la directory di cui dovremo fare il deploy:
npm run build
Questo specifico progetto (ol-app) utilizza Vite anche per il build.
The project will be built into the **dist** directory, with can be deployed to the web server. Beware that references to Javascript and CSS into the **index.html** are absolute.
cd ~
du -sh .npm/ .degit/ src/openlayers-test/dist/
16M .npm/
36K .degit/
1.7M src/openlayers-test/dist/
===== Sviluppo =====
==== Produrre HREF relativi ====
Il build di ol-app viene eseguito con il tool Vite. Il codice **JavaScript** e i **CSS** vengono assemblati in due file contenuti nella sottodirectory **assets/** e inclusi con link assoluti:
My OpenLayers App
Questo impedisce di fare il deploy in una sottodirectory a scelta. È possibile configurare l'opzione **%%--base%%** da passare al build di Vite modificando il file **package.json**, nella sezione **scripts** => **build**:
{
"scripts": {
"build": "vite build --base=./"
}
}
==== Aggiungere directory al deploy ====
Se ci sono dei file statici o intere directory da aggiungere al deploy, è possibile creare la cartella **public/**, nell'ambiente di sviluppo. Tutto il suo contenuto verrà incluso nella directory radice durante il **vite build** (cioè in **dist/**).
Durante il test e lo sviluppo (ambiente attivato da **npm start**), i file contenuti in **public/** devono essere linkati senza il prefisso ''public'', ma con il percorso che avranno nel build. Ad esempio per creare un VectorLayer dal file ''public/aeroporto/sesto_fiorentino.kml'':
const sesto_fiorentino = new VectorLayer({
source: new VectorSource({url: 'aeroporto/sesto_fiorentino.kml',
format: new KML({extractStyles: false})})
});
==== Rinominare il file index.html ====
Potrebbe capitare il caso in cui il progetto in questione deve essere inserito in un sito già esistente, eventualmente in una sottodirectory e con un nome della pagina iniziale diverso da **index.html**.
Nei paragrafi sopra si è già visto come generare link relativi. Per modificare il nome del file index.html si deve anzitutto modificare **vite.config.js** definendo //build// => //rollupOptions// => //input// => //main// necessario per eseguire il corretto build e //server// => //open// per eseguire correttamente il server in fase di sviluppo:
export default {
build: {
sourcemap: true,
rollupOptions: {
input: {
main: 'my-index.html' // The entry file.
}
}
},
server: {
open: '/my-index.html' // Entry file for the dev server.
}
}
Anche il file **package.json** va modificando nella sezione //scripts// => //dev// aggiungendo l'opzione **%%--open%%** al comando ''vite'':
{
"name": "openlayers-test",
"version": "1.0.4",
"scripts": {
"dev": "vite --open my-index.html",
...
==== Dipendenze del progetto ====
Nel nostro file **package.json** si trova:
"dependencies": {
"ol": "latest"
}
Cioè il progetto dipende dalla versione più recente di **create-ol**. Si tratta di un initializer che //Scaffolds an OpenLoader plugin with massive customization//. Durante il **create** iniziale è stata installata la versione **create-ol@1.0.1**
In generale non avviene un aggiornamento automatico, a meno che non venga eseguito uno dei seguenti comandi:
npm update
npm install @latest
npm update
Volendo è possibile modificare il file **package.json** e indicare una versione specifica:
"dependencies": {
"ol": "1.0.1"
}
Il numero di versione può essere preceduto da caratteri speciali,ad esempio **%%^X.Y.Z%%** oppure **%%~X.Y.Z%%**. Nel primo caso sono consentiti aggiornamenti mantenendo ferma la //major version// X (eccezione se X vale 0: allora sono consentiti aggiornamenti solo di //patch version//). Nel secondo caso sono consentiti solo aggiornamenti di //patch version// Z, mentre //major// e //minor version// devono restare uguali.
==== Il file package-lock.json ====
Nella directory del progetto si trova il file **package-lock.json** che viene creato e aggiornato ogni volta che si installa o si aggiorna un pacchetto (''npm install'', ''npm update''). Nel nostro caso l'install è stata diretta conseguenza del ''npm create''. Il file **non deve essere modificato** a mano, eventualmente lo si può eliminare insieme alla directory ''node_modules/'' ed eseguendo di nuovo ''npm install'' viene creato ex-novo, così come il download dei pacchetti.
Nel file **package-lock.json** si vede la dipendenza dai vari packages, tra cui la libreria OpenLayers:
{
"name": "ol-vite",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
...
},
"node_modules/ol": {
"version": "10.4.0",
"resolved": "https://registry.npmjs.org/ol/-/ol-10.4.0.tgz",
...
}
Il tutto è stato scaricato nella directory di lavoro **node_modules/**, per cui è importante mantenere copia di questa directory di lavoro che in pratica contiene il codice sorgente delle varie componenti scaricato al momento del //create//.
===== Automatizzare il deploy =====
È possibile definire il comando per effettuare il deploy del progetto aggiungendo a **package.json** uno //scripts// => //deploy//:
"scripts": {
"deploy": "rsync -avz ./dist/ ./ user@yourserver:/path/to/project"
}
Il deploy quindi si esegue con
npm run deploy
===== Web References =====
* **[[https://openlayers.org/doc/quickstart.html]]**