rigacci.org

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 =====

<code>
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] 
</code>

===== Inizializzazione di un pacchetto =====

<code>
npm create ol-app openlayers-test
Need to install the following packages:
  create-ol-app@1.2.0
Ok to proceed? (y) y
</code>

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**:

<code>
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
...
</code>

===== Il registry (repository) =====

Per sapere quale //registry// si sta utilizzando:

<code>
npm config ls -l | grep '^registry ='
registry = "https://registry.npmjs.org/" 
</code>

Per avere informazioni più dettagliate su un intializer (ad esempio conoscere l'URL per scaricarlo dal registry):

<code>
npm view create-ol-app
...
dist
.tarball: https://registry.npmjs.org/create-ol-app/-/create-ol-app-1.2.0.tgz
...
</code>

===== 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:

<code>
du -sh openlayers-test/
42M     openlayers-test/
</code>

===== Esecuzione in  ambiente test =====

È possibile eseguire il progetto in un ambiente di test con il comando **npm start**:

<code>
cd openlayers-test/
npm start
</code>

Questo specifico progetto utilizza il tool **Vite** (scaricato come dipendenza) per offrire un server web locale:

<code>
  VITE v6.2.2  ready in 315 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help
</code>

===== Preparazione per il deploy =====

Con il comando **npm run build** si genera la directory di cui dovremo fare il deploy:

<code>
npm run build
</code>

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.

<code>
cd ~
du -sh .npm/ .degit/ src/openlayers-test/dist/
16M     .npm/
36K     .degit/
1.7M    src/openlayers-test/dist/
</code>

===== 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:

<code xml>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My OpenLayers App</title>
    <script type="module" crossorigin src="/assets/index-Ch4sRF4c.js"></script>
    <link rel="stylesheet" crossorigin href="/assets/index-A7cyoH51.css">
  </head>
</code>

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**:

<code>
{
  "scripts": {
    "build": "vite build --base=./"
  }
}
</code>

==== 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'':

<code javascript>
const sesto_fiorentino = new VectorLayer({
    source: new VectorSource({url: 'aeroporto/sesto_fiorentino.kml',
    format: new KML({extractStyles: false})})
});
</code>

==== 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:

<code>
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.
  }
}
</code>


Anche il file **package.json** va modificando nella sezione //scripts// => //dev// aggiungendo l'opzione **%%--open%%** al comando ''vite'':

<code>
{
  "name": "openlayers-test",
  "version": "1.0.4",
  "scripts": {
    "dev": "vite --open my-index.html",
    ...
</code>


==== Dipendenze del progetto ====

Nel nostro file **package.json** si trova:

<code>
"dependencies": {
  "ol": "latest"
}
</code>

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:

<code>
npm update <package-name>
npm install <package-name>@latest
npm update
</code>

Volendo è possibile modificare il file **package.json** e indicare una versione specifica:

<code>
"dependencies": {
  "ol": "1.0.1"
}
</code>

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:

<code>
{
  "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",
      ...
}
</code>

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//:

<code>
"scripts": {
  "deploy": "rsync -avz ./dist/ ./ user@yourserver:/path/to/project"
}
</code>

Il deploy quindi si esegue con

<code>
npm run deploy
</code>

===== Web References =====

  * **[[https://openlayers.org/doc/quickstart.html]]**