Installer le SDK TypeScript Mistral

Leçon corrigée le 3 novembre 2026 après une exécution réelle des exemples avec le SDK @mistralai/mistralai 3.5.0 et TypeScript 7.0.2. Telle qu’elle était écrite, elle ne compilait pas. npx tsc, sans TypeScript installé, télécharge le paquet npm tsc, une version abandonnée du compilateur (2.0.4). Le script de test se trouvait hors du dossier src déclaré dans tsconfig.json. process n’est reconnu qu’avec @types/node. Enfin, le mode strict refuse models.data.length et model.id sans vérification préalable. Le tsconfig.json suit désormais le cas « compiler puis exécuter avec Node.js » du guide TypeScript, et Node.js 18 et 20, arrivés en fin de vie, ne sont plus présentés comme suffisants. Sources : Download TypeScript · Choosing compiler options (TypeScript) · changements de TypeScript 6.0 · tsx et TypeScript · environnements pris en charge par le SDK · calendrier des versions de Node.js.

Pourquoi un SDK TypeScript ?

Si votre stack technique repose sur Node.js, Deno ou Bun, le SDK TypeScript de Mistral vous permet d’intégrer les modèles directement dans vos applications JavaScript et TypeScript, sans passer par une couche Python intermédiaire ni écrire vos propres appels HTTP. C’est le cas le plus courant lorsque l’IA arrive dans une application web existante : une API Express, un backend Next.js, un worker Node qui traite une file de messages.

Le typage statique de TypeScript apporte une sécurité supplémentaire, et elle se mesure dès la première heure de développement. Votre éditeur complète les noms de paramètres au lieu de vous laisser deviner entre maxTokens et max_tokens ; une erreur de casse ou un champ inventé est signalé à la compilation, pas en production à trois heures du matin ; et la documentation des paramètres s’affiche au survol, sans quitter le fichier. Ce filet de sécurité compte d’autant plus que les réponses de l’API sont des objets imbriqués où il est facile de se tromper d’un niveau.

Ce qu’il vous faut avant de commencer

Le SDK vise les versions LTS de Node.js encore maintenues. Au 3 novembre 2026, ce sont les versions 22, 24 et 26 ; Node.js 18 et 20 ne reçoivent plus de correctifs de sécurité. Vérifiez la vôtre avec node --version avant toute chose : le SDK repose sur les modules ES et sur l’API fetch native. Il vous faut ensuite un gestionnaire de paquets, npm, yarn ou pnpm au choix, et une clé API Mistral déjà créée et disponible en variable d’environnement, comme vu dans les leçons précédentes.

Installation

Le SDK officiel est publié sur npm sous le nom @mistralai/mistralai :

# Avec npm
npm install @mistralai/mistralai

# Avec yarn
yarn add @mistralai/mistralai

# Avec pnpm
pnpm add @mistralai/mistralai

Configuration TypeScript

Si vous utilisez TypeScript, ce que nous recommandons, installez trois outils comme dépendances de développement : le compilateur, tsx, qui exécute un fichier .ts sans étape de compilation, et @types/node, qui décrit à TypeScript les objets de Node.js comme process :

npm install -D typescript tsx @types/node

Ne sautez pas cette étape : sans TypeScript installé dans le projet, npx tsc irait chercher sur npm le paquet tsc, une ancienne version abandonnée du compilateur (2.0.4), et non TypeScript. Déclarez ensuite le projet en modules ES, comme le demande la documentation TypeScript pour un code compilé puis exécuté par Node.js :

npm pkg set type=module

Créez enfin le tsconfig.json. Il reprend les réglages que le guide officiel de TypeScript donne pour ce cas (module: nodenext). Il active aussi le mode strict, qui vous obligera à traiter les valeurs potentiellement absentes dans les réponses de l’API — une contrainte salutaire —, et compile src/ vers dist/ :

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

Trois lignes méritent une explication, car chacune évite une erreur que nous avons rencontrée en testant cette leçon :

• "types": ["node"] charge les types de Node.js. Depuis TypeScript 6.0, les paquets @types ne sont plus chargés automatiquement : sans cette ligne, process.env provoque l’erreur « Cannot find name ‘process’ », même avec @types/node installé.
• "rootDir": "src" fixe l’origine des fichiers compilés : src/test-mistral.ts devient dist/test-mistral.js. Sans elle, TypeScript 7 signale l’erreur TS5011 dès que vos sources ne sont pas à la racine du projet.
• "skipLibCheck": true évite de revérifier les fichiers de types des dépendances ; c’est aussi un réglage du tsconfig.json que génère npx tsc --init. Avec le SDK 3.5.0, TypeScript 7 signale sinon une erreur dans les déclarations du SDK lui-même, que votre code n’a aucun moyen de corriger.

Le SDK est publié en modules ES et embarque ses propres types : aucun paquet @types/ n’est nécessaire pour lui. Si votre éditeur ne propose pas l’auto-complétion, le problème vient de votre tsconfig.json, pas d’un paquet de types manquant.

Configurer la variable d’environnement

La clé API ne doit jamais figurer dans le code source. En Node.js, la solution habituelle consiste à installer dotenv, qui charge les variables depuis un fichier local au démarrage du processus :

npm install dotenv

Créez le fichier .env à la racine de votre projet :

MISTRAL_API_KEY=votre-cle-api-ici

Puis ajoutez immédiatement ce fichier à votre .gitignore, avant même le premier commit — c’est le moment précis où les clés fuitent :

.env
.env.local

L’import dotenv/config doit précéder toute lecture de process.env, sinon la variable sera encore indéfinie au moment où vous construisez le client :

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

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

Vérifier l’installation

Avant d’écrire la moindre logique métier, validez la chaîne complète — installation, clé, réseau — avec un script minimal. Créez src/test-mistral.ts et demandez simplement la liste des modèles accessibles à votre compte :

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

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

  // Lister les modèles disponibles
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Modèles disponibles : ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Un type de modèle inconnu de cette version du SDK arrive marqué 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Les deux vérifications ne sont pas décoratives. Le SDK déclare data facultatif, et chaque entrée de la liste est soit une fiche de modèle de base, soit une fiche de modèle affiné, soit une valeur inconnue (type: 'UNKNOWN') : quand l’API ajoute un nouveau type de modèle, le SDK le conserve sous cette forme au lieu de planter. Sans ces deux tests, le mode strict refuse de compiler.

En développement, exécutez-le avec tsx, installé plus haut, qui transpile à la volée et vous évite une étape :

npx tsx src/test-mistral.ts

Attention : tsx ne vérifie pas les types, il les retire et exécute. Seul tsc signale les erreurs de typage ; lancez npx tsc --noEmit pour vérifier sans compiler. Pour compiler puis exécuter, ce que fera votre pipeline de build :

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

Une clé valide affiche le nombre de modèles et les cinq premiers. Une clé refusée affiche une erreur Status 401 (Invalid API Key) : la chaîne fonctionne, seule la clé est en cause.

Organiser le projet

Une fois la vérification passée, structurez le projet pour que la clé et le client ne se dispersent pas dans tous les fichiers :

mon-projet/
├── src/
│   ├── index.ts          # Point d'entrée
│   ├── mistral-client.ts # Initialisation du client (singleton)
│   └── utils/
├── .env                  # Variables d'environnement (git-ignoré)
├── .gitignore
├── package.json
└── tsconfig.json

Centraliser l’initialisation du client dans un module dédié évite de le recréer dans chaque fichier et, surtout, fait échouer l’application au démarrage plutôt qu’au premier appel utilisateur si la clé manque :

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

if (!process.env.MISTRAL_API_KEY) {
  throw new Error('La variable MISTRAL_API_KEY est requise.');
}

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

Le reste du code n’a plus qu’à importer ce client déjà construit :

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

Notez l’extension .js dans l’import relatif : avec module: nodenext, TypeScript exige le nom du fichier tel qu’il existera après compilation, et tsx sait le relier au fichier .ts. L’ordre des imports compte aussi : dotenv/config est exécuté avant mistral-client.js, si bien que la clé est déjà chargée quand ce module vérifie sa présence.

Points clés à retenir

• Le SDK TypeScript s’installe avec npm install @mistralai/mistralai
• L’import principal est import { Mistral } from '@mistralai/mistralai'
• Installez typescript, tsx et @types/node en dépendances de développement avant d’appeler npx tsc
• module: nodenext et "type": "module" pour du code compilé puis exécuté par Node.js ; les imports relatifs prennent l’extension .js
• Utilisez un fichier .env avec dotenv pour gérer la clé API
• Le SDK fournit des types TypeScript natifs : profitez de l’auto-complétion, et laissez tsc vérifier ce que tsx ne vérifie pas
• Centralisez l’initialisation du client dans un module dédié