ES Modules in JavaScript: import, export e caricamento dinamico

Un modulo è un file con il suo scope

Prima che esistessero gli ES Modules, ogni tag <script> riversava le sue variabili nel namespace globale, e l'ordine di caricamento decideva chi vedeva cosa. Gli ES Modules risolvono il problema dando a ogni file il proprio scope. Niente esce se non fai esplicitamente export. Niente entra se non fai esplicitamente import.

Due file, uno che esporta e uno che importa:

// math.js
export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

// main.js
import { add, multiply } from './math.js';

console.log(add(2, 3));
console.log(multiply(4, 5));

add e multiply vivono in math.js. Diventano visibili in main.js solo grazie all'import. Nient'altro in math.js, che siano helper, costanti o qualsiasi altra cosa, è raggiungibile dall'esterno.

Da qui derivano due regole che conviene assimilare presto:

• I moduli girano automaticamente in strict mode. Non serve 'use strict'.
• Il this di primo livello è undefined, non l'oggetto globale.

Export con nome: esporta man mano

È la forma più comune. Metti export davanti a qualsiasi function, class, const o let e diventa parte dell'interfaccia pubblica del modulo:

// shapes.js
export const PI = 3.14159;

export function circleArea(r) {
  return PI * r * r;
}

export class Square {
  constructor(side) {
    this.side = side;
  }
  area() {
    return this.side ** 2;
  }
}

// main.js
import { PI, circleArea, Square } from './shapes.js';

console.log(PI);
console.log(circleArea(5));
console.log(new Square(4).area());

I nomi tra graffe devono corrispondere esattamente ai nomi esportati: import { circlearea } fallirebbe. Se un nome è in conflitto con qualcosa che hai già, rinominalo in fase di import con as:

// shapes.js
export function area(r) {
  return 3.14159 * r * r;
}

// main.js
import { area as circleArea } from './shapes.js';

console.log(circleArea(10));

Puoi anche elencare gli export in fondo al file invece che in linea, cosa che alcuni preferiscono per avere una sezione "API pubblica" ben visibile:

// shapes.js
function area(r) {
  return 3.14159 * r * r;
}
const PI = 3.14159;

export { area, PI };

// main.js
import { area, PI } from './shapes.js';
console.log(area(PI));

Entrambi gli stili danno lo stesso risultato. Scegline uno e resta coerente all'interno di un progetto.

Export default: uno per modulo

Un modulo può anche avere un singolo export default. I default sono pensati per i file che hanno davvero una cosa principale: un componente, una classe, un oggetto di configurazione:

// logger.js
export default function log(message) {
  console.log(`[log] ${message}`);
}

// main.js
import log from './logger.js';

log('server started');

Tre cose da notare:

• Niente graffe attorno a log nell'import.
• Il nome importato è quello che vuoi tu. import shout from './logger.js' funzionerebbe allo stesso modo.
• Un solo export default per file. Se provi ad aggiungerne un secondo, il file non verrà interpretato.

Export con nome e default possono convivere:

// logger.js
export default function log(message) {
  console.log(`[log] ${message}`);
}

export function warn(message) {
  console.warn(`[warn] ${message}`);
}

// main.js
import log, { warn } from './logger.js';

log('booting');
warn('low disk space');

Prima il default, poi quelli con nome tra graffe. L'ordine è fisso.

Quale usare? Gli export con nome sono più facili da rifattorizzare: rinominare in tutta la codebase è un semplice trova e sostituisci, perché ogni import usa lo stesso nome. I default sono flessibili, ma lasciano a ogni chiamante la libertà di scegliere un nome diverso, e questo rende più difficili le ricerche con grep. La maggior parte delle guide di stile moderne preferisce gli export con nome e riserva il default ai moduli con un unico scopo reale.

Importare tutto, riesportare, effetti collaterali

Altre forme di import che incontrerai.

Raccogliere tutti gli export con nome in un unico oggetto namespace:

// shapes.js
export const PI = 3.14159;
export function area(r) { return PI * r * r; }

// main.js
import * as shapes from './shapes.js';

console.log(shapes.PI);
console.log(shapes.area(3));

Riesportare da un altro modulo senza importare nello scope corrente:

// index.js
export { area, PI } from './shapes.js';
export { default as log } from './logger.js';

Con questo pattern i punti di ingresso delle librerie raccolgono i pezzi dai file interni in un'unica interfaccia pubblica.

E infine, un import senza alcun binding, per i moduli il cui unico compito sono gli effetti collaterali (polyfill, CSS-in-JS, registrazione di handler):

import './polyfills.js';

Il file viene eseguito una volta; non viene importato niente per nome.

Gli import sono statici e live

Due proprietà di import che ogni tanto sorprendono.

Statici. Le dichiarazioni import vengono risolte prima che venga eseguita qualsiasi parte del tuo codice. Non puoi metterne una dentro un if, una funzione o un try. Il percorso deve essere una stringa letterale, non una variabile. È questo che permette agli strumenti di analizzare gli import senza eseguire il codice: bundler, type checker e tree-shaker si basano tutti su questo.

// Not allowed - SyntaxError.
if (userWantsFancy) {
  import { fancy } from './fancy.js';
}

Se ti serve un caricamento condizionale, usa import() (lo vediamo tra poco).

Live. Un binding importato è un riferimento in sola lettura all'export, non una copia istantanea. Se il modulo che esporta riassegna il valore, chi importa vede il nuovo valore:

// counter.js
export let count = 0;
export function increment() {
  count += 1;
}

// main.js
import { count, increment } from './counter.js';

console.log(count);
increment();
increment();
import('./counter.js').then(m => console.log(m.count));

Inoltre non puoi riassegnare un import dal lato di chi lo usa: count = 5 in main.js lancerebbe un errore. Gli import sono viste in sola lettura.

import() dinamico per caricare su richiesta

Quando devi decidere a runtime se caricare un modulo (funzionalità pesanti, code splitting per route, polyfill condizionali), usa import() come funzione. Restituisce una promise che si risolve con gli export del modulo:

async function loadChart() {
  const chart = await import('./chart.js');
  chart.render();
}

document.querySelector('#show-chart')?.addEventListener('click', loadChart);

Visto che è una normale chiamata di funzione, puoi:

• Fare await dentro una funzione async.
• Passare una variabile come percorso.
• Usarla dentro un if o un try/catch.

Il destructuring dell'oggetto risolto funziona come con un import statico:

const { default: log, warn } = await import('./logger.js');
log('loaded dynamically');
warn('careful now');

Quando fai destructuring, default è la chiave dell'export default. Rinominala come preferisci.

I casi d'uso pratici sono il code-splitting (scaricare la libreria dei grafici solo quando l'utente clicca "mostra grafico"), i polyfill basati sul feature detection e i plugin scoperti a runtime.

Eseguire gli ES Modules: browser e Node

La sintassi è la stessa ovunque; quello che cambia è come il runtime trova e carica il file.

Nel browser, marca lo script di ingresso come modulo:

<script type="module" src="./main.js"></script>

Con type="module", il browser rispetta import/export, esegue il codice in strict mode e rimanda l'esecuzione a dopo il parsing dell'HTML. I percorsi devono essere relativi (./, ../) o URL assoluti: gli specificatori nudi come import 'lodash' non funzionano senza una import map o un bundler.

In Node, ci sono due modi per attivarli:

• Dare al file l'estensione .mjs, oppure
• Impostare "type": "module" nel package.json più vicino, così ogni file .js diventa un modulo.

Node richiede anche percorsi completi con estensione: import './utils.js', non import './utils'.

// package.json
{
  "type": "module",
  "main": "./index.js"
}

Entrambi gli ambienti richiedono estensioni esplicite nell'ESM nativo. I bundler (Vite, webpack, esbuild) risolvono per te i percorsi senza estensione durante lo sviluppo: comodo, ma affidarti a questo significa che il tuo sorgente non girerà senza la fase di build.

Errori comuni

Alcune cose che mettono in difficoltà:

• Dimenticare type="module" nel browser. Senza, <script> viene eseguito come script classico e import è un errore di sintassi.
• Estensioni mancanti in Node. import './utils' fallisce; import './utils.js' funziona. I bundler lo nascondono, i runtime nativi no.
• Aspettarsi __dirname o require in un ES Module. Esistono solo in CommonJS. In ESM, usa import.meta.url e convertilo quando ti serve un percorso.
• Import circolari che toccano valori non ancora pronti. Due moduli che si importano a vicenda sono permessi, ma leggere un export non ancora assegnato ti restituisce undefined. Struttura il codice in modo che il ciclo non venga attraversato durante l'inizializzazione, oppure spezzalo.
• Provare a fare import in modo condizionale. L'istruzione statica import non lo consente. Usa l'import() dinamico per tutto ciò che dipende dal runtime.

Prossimo passo: CommonJS vs ESM

Gli ES Modules sono lo standard, ma molto codice Node in circolazione usa ancora CommonJS: require, module.exports e un insieme diverso di regole su quando viene eseguito il codice. Conoscerli entrambi, e sapere come interagiscono, è il tema della prossima pagina.