Installer le SDK TypeScript Mistral

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 exige Node.js en version 18 ou supérieure — vérifiez-le avec node --version avant toute chose, car une version antérieure échouera sur les modules ES et 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, assurez-vous que votre tsconfig.json est correctement configuré. La configuration ci-dessous cible les modules ES et active le mode strict, qui vous obligera à traiter les valeurs potentiellement absentes dans les réponses de l’API — une contrainte salutaire :

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Le SDK utilise des modules ES et embarque ses propres types TypeScript natifs. Aucune déclaration @types/ supplémentaire n’est nécessaire : 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 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();
  console.log(`Modèles disponibles : ${models.data.length}`);

  for (const model of models.data.slice(0, 5)) {
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

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

npx tsx test-mistral.ts

Ou compilez puis exécutez, ce qui correspond à ce que fera votre pipeline de build :

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

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

Points clés à retenir

• Le SDK TypeScript s’installe avec npm install @mistralai/mistralai
• L’import principal est import { Mistral } from '@mistralai/mistralai'
• 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
• Centralisez l’initialisation du client dans un module dédié