Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Installare l'SDK TypeScript di Mistral

Lezione 8 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché usare l’SDK TypeScript?
  2. Prerequisiti
  3. Installazione
  4. Configurazione di TypeScript
  5. Configurare la Variabile d’Ambiente
  6. Verificare l’Installazione
  7. Organizzare il Progetto
  8. Punti chiave

Lezione aggiornata il 3 novembre 2026 dopo aver eseguito gli esempi con l’SDK @mistralai/mistralai versione 3.5.0 e TypeScript 7.0.2. La versione originale non si compilava. L’esecuzione di npx tsc senza TypeScript installato scarica il pacchetto npm abbandonato tsc (versione 2.0.4) invece del compilatore. Lo script di test si trovava fuori dalla cartella src dichiarata in tsconfig.json. L’oggetto process viene riconosciuto solo con @types/node. Infine, la modalità strict rifiuta models.data.length e model.id senza una validazione preliminare. Il file tsconfig.json segue ora lo scenario “compila poi esegui con Node.js” della guida TypeScript; Node.js 18 e 20, giunti alla fine del loro ciclo di vita, non sono più elencati come sufficienti. Fonti: Download TypeScript · Choosing compiler options (TypeScript) · TypeScript 6.0 changes · tsx and TypeScript · SDK supported runtimes · Node.js release schedule.

Perché usare l’SDK TypeScript?

Se il tuo stack si basa su Node.js, Deno o Bun, l’SDK TypeScript di Mistral ti permette di integrare i modelli direttamente nelle tue applicazioni JavaScript e TypeScript. Eviti livelli intermedi in Python o la scrittura di chiamate HTTP personalizzate. Questo è lo scenario più comune quando aggiungi l’IA a un’applicazione web esistente: un’API Express, un backend Next.js o un worker Node che elabora una coda di messaggi.

La tipizzazione statica di TypeScript aggiunge una rete di sicurezza che ripaga già nella prima ora di sviluppo. Il tuo editor completa i nomi dei parametri invece di farti indovinare tra maxTokens e max_tokens; gli errori di maiuscole/minuscole o i campi inventati scattano in fase di compilazione, non in produzione alle 3 del mattino; e la documentazione dei parametri appare al passaggio del mouse senza dover lasciare il file. Questa rete di sicurezza conta ancora di più perché le risposte delle API sono oggetti annidati dove è facile perdere un livello.

Prerequisiti

L’SDK mira alle versioni LTS mantenute di Node.js. Al 3 novembre 2026, queste sono le versioni 22, 24 e 26; Node.js 18 e 20 non ricevono più patch di sicurezza. Controlla la tua versione con node --version prima di procedere: l’SDK si basa sui moduli ES e sull’API nativa fetch. Hai anche bisogno di un gestore di pacchetti (npm, yarn o pnpm) e di una chiave API Mistral creata e disponibile come variabile d’ambiente, come trattato nelle lezioni precedenti.

Installazione

L’SDK ufficiale è pubblicato su npm come @mistralai/mistralai:

# Con npm
npm install @mistralai/mistralai

# Con yarn
yarn add @mistralai/mistralai

# Con pnpm
pnpm add @mistralai/mistralai

Configurazione di TypeScript

Se usi TypeScript, cosa che raccomandiamo, installa tre strumenti come dipendenze di sviluppo: il compilatore, tsx (che esegue file .ts senza passaggio di build) e @types/node (che descrive a TypeScript gli oggetti Node.js come process):

npm install -D typescript tsx @types/node

Non saltare questo passaggio. Senza TypeScript installato nel progetto, npx tsc recupera il pacchetto tsc da npm: un compilatore legacy abbandonato (2.0.4) invece di TypeScript. Successivamente, dichiara il progetto come moduli ES, come richiesto dalla documentazione TypeScript per il codice compilato e poi eseguito da Node.js:

npm pkg set type=module

Infine, crea tsconfig.json. Usa le impostazioni che la guida ufficiale TypeScript raccomanda per questo scenario (module: nodenext). Abilita anche la modalità strict, che ti forza a gestire valori potenzialmente mancanti nelle risposte API (un vincolo salutare) e compila src/ in dist/:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

Tre righe meritano una spiegazione, poiché ciascuna previene un errore riscontrato durante il test di questa lezione:

  • "types": ["node"] carica i tipi di Node.js. Da TypeScript 6.0, i pacchetti @types non vengono più caricati automaticamente. Senza questa riga, process.env genera l’errore “Cannot find name ‘process’”, anche con @types/node installato.
  • "rootDir": "src" imposta la radice sorgente per i file compilati: src/test-mistral.ts diventa dist/test-mistral.js. Senza di essa, TypeScript 7 riporta l’errore TS5011 ogni volta che le tue sorgenti non si trovano alla radice del progetto.
  • "skipLibCheck": true salta il controllo dei tipi nei file di dichiarazione delle dipendenze. Questa è anche un’impostazione predefinita in tsconfig.json generato da npx tsc --init. Con l’SDK 3.5.0 e TypeScript 7, omettere questo causa un errore nelle dichiarazioni stesse dell’SDK che il tuo codice non può correggere.

L’SDK è pubblicato come moduli ES e include i propri tipi: non serve nessun pacchetto @types/ per esso. Se il tuo editor manca di auto-completamento, il problema risiede nel tuo tsconfig.json, non in un pacchetto di tipi mancante.

Configurare la Variabile d’Ambiente

Non inserire mai hardcoded la chiave API nel tuo codice sorgente. In Node.js, la soluzione standard è dotenv, che carica le variabili da un file locale all’avvio del processo:

npm install dotenv

Crea un file .env alla radice del tuo progetto:

MISTRAL_API_KEY=your-api-key-here

Aggiungi immediatamente questo file al tuo .gitignore, prima del tuo primo commit. Questo è il momento esatto in cui le chiavi fuoriescono:

.env
.env.local

L’importazione dotenv/config deve precedere qualsiasi lettura di process.env. Altrimenti, la variabile rimane undefined quando istanzi il client:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

Verificare l’Installazione

Prima di scrivere la logica di business, valida l’intera catena: installazione, chiave, rete, con uno script minimale. Crea src/test-mistral.ts e richiedi semplicemente l’elenco dei modelli accessibili al tuo account:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

async function main() {
  const client = new Mistral({
    apiKey: process.env.MISTRAL_API_KEY,
  });

  // Elenca i modelli disponibili
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Un tipo di modello sconosciuto a questa versione dell'SDK è contrassegnato come 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Questi due controlli non sono decorativi. L’SDK dichiara data come opzionale e ogni voce dell’elenco è una scheda modello base, una scheda modello fine-tuned o un valore sconosciuto (type: 'UNKNOWN'). Quando l’API aggiunge un nuovo tipo di modello, l’SDK lo conserva in questa forma invece di andare in crash. Senza questi due test, la modalità strict rifiuta la compilazione.

In sviluppo, eseguilo con tsx, installato in precedenza, che transpila al volo e ti risparmia un passaggio di build:

npx tsx src/test-mistral.ts

Attenzione: tsx non controlla i tipi; li rimuove ed esegue. Solo tsc riporta gli errori di tipizzazione. Esegui npx tsc --noEmit per controllare senza compilare. Per compilare e poi eseguire, come farà la tua pipeline di build:

npx tsc && node dist/test-mistral.js

Una chiave valida visualizza il conteggio dei modelli e le prime cinque voci. Una chiave rifiutata visualizza un errore Status 401 (Invalid API Key): la catena funziona, è solo la chiave ad essere errata.

Organizzare il Progetto

Una volta superata la verifica, struttura il progetto in modo che chiave e client non siano sparsi tra i file:

mon-projet/
├── src/
│   ├── index.ts          # Punto di ingresso
│   ├── mistral-client.ts # Inizializzazione client (singleton)
│   └── utils/
├── .env                  # Variabili d'ambiente (ignorate da git)
├── .gitignore
├── package.json
└── tsconfig.json

Centralizzare l’inizializzazione del client in un modulo dedicato evita di ricrearlo in ogni file. Ancora più importante, fa sì che l’applicazione fallisca all’avvio piuttosto che alla prima chiamata dell’utente se la chiave manca:

// src/mistral-client.ts
import { Mistral } from '@mistralai/mistralai';

if (!process.env.MISTRAL_API_KEY) {
  throw new Error('The MISTRAL_API_KEY variable is required.');
}

export const mistral = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

Il resto del codice importa semplicemente questo client pre-costruito:

// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';

Nota l’estensione .js nell’importazione relativa. Con module: nodenext, TypeScript richiede il nome del file così come esisterà dopo la compilazione, e tsx sa come mapparlo al file .ts. Anche l’ordine di importazione conta: dotenv/config viene eseguito prima di mistral-client.js, quindi la chiave è caricata quando quel modulo ne verifica la presenza.

Punti chiave

  • Installa l’SDK TypeScript con npm install @mistralai/mistralai
  • L’importazione principale è import { Mistral } from '@mistralai/mistralai'
  • Installa typescript, tsx e @types/node come dipendenze di sviluppo prima di chiamare npx tsc
  • Usa module: nodenext e "type": "module" per il codice compilato e poi eseguito da Node.js; le importazioni relative prendono l’estensione .js
  • Usa un file .env con dotenv per gestire la chiave API
  • L’SDK fornisce tipi TypeScript nativi: sfrutta l’auto-completamento e lascia che tsc controlli ciò che tsx salta
  • Centralizza l’inizializzazione del client in un modulo dedicato