User Tools

Site Tools


doc:appunti:prog:nodejs

Node.js

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:

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

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

{
  "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 buildrollupOptionsinputmain necessario per eseguire il corretto build e serveropen 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 scriptsdev 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 <package-name>
npm install <package-name>@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 scriptsdeploy:

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

Il deploy quindi si esegue con

npm run deploy

Web References

doc/appunti/prog/nodejs.txt · Last modified: 2025/03/27 11:58 by niccolo