Install the Mistral TypeScript SDK — Mistral API: Quick Start

Lesson updated November 3, 2026 after running the examples with @mistralai/mistralai SDK 3.5.0 and TypeScript 7.0.2. The original version did not compile. Running npx tsc without TypeScript installed downloads the abandoned tsc npm package (version 2.0.4) instead of the compiler. The test script was located outside the src folder declared in tsconfig.json. The process object is only recognized with @types/node. Finally, strict mode rejects models.data.length and model.id without prior validation. The tsconfig.json now follows the TypeScript guide’s “compile then run with Node.js” scenario, and Node.js 18 and 20, which have reached end-of-life, are no longer listed as sufficient. Sources: Download TypeScript · Choosing compiler options (TypeScript) · TypeScript 6.0 changes · tsx and TypeScript · SDK supported runtimes · Node.js release schedule.

Why use the TypeScript SDK?

If your stack relies on Node.js, Deno, or Bun, the Mistral TypeScript SDK lets you integrate models directly into your JavaScript and TypeScript applications. You avoid intermediate Python layers or writing custom HTTP calls. This is the most common scenario when adding AI to an existing web application: an Express API, a Next.js backend, or a Node worker processing a message queue.

TypeScript’s static typing adds a safety net that pays off within the first hour of development. Your editor completes parameter names instead of making you guess between maxTokens and max_tokens; casing errors or invented fields trigger at compile time, not in production at 3 AM; and parameter documentation appears on hover without leaving the file. This safety net matters even more because API responses are nested objects where it is easy to miss a level.

Prerequisites

The SDK targets maintained LTS versions of Node.js. As of November 3, 2026, these are versions 22, 24, and 26; Node.js 18 and 20 no longer receive security patches. Check your version with node --version before proceeding: the SDK relies on ES modules and the native fetch API. You also need a package manager (npm, yarn, or pnpm) and a Mistral API key created and available as an environment variable, as covered in previous lessons.

Installation

The official SDK is published on npm as @mistralai/mistralai:

# With npm
npm install @mistralai/mistralai

# With yarn
yarn add @mistralai/mistralai

# With pnpm
pnpm add @mistralai/mistralai

TypeScript Configuration

If you use TypeScript—which we recommend—install three tools as development dependencies: the compiler, tsx (which runs .ts files without a build step), and @types/node (which describes Node.js objects like process to TypeScript):

npm install -D typescript tsx @types/node

Do not skip this step. Without TypeScript installed in the project, npx tsc fetches the tsc package from npm—an abandoned legacy compiler (2.0.4)—instead of TypeScript. Next, declare the project as ES modules, as the TypeScript documentation requires for code compiled then run by Node.js:

npm pkg set type=module

Finally, create tsconfig.json. It uses the settings the official TypeScript guide recommends for this scenario (module: nodenext). It also enables strict mode, which forces you to handle potentially missing values in API responses—a healthy constraint—and compiles src/ to dist/:

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

Three lines deserve explanation, as each prevents an error we encountered while testing this lesson:

"types": ["node"] loads Node.js types. Since TypeScript 6.0, @types packages are no longer loaded automatically. Without this line, process.env triggers the error “Cannot find name ‘process’”, even with @types/node installed.
"rootDir": "src" sets the source root for compiled files: src/test-mistral.ts becomes dist/test-mistral.js. Without it, TypeScript 7 reports error TS5011 whenever your sources are not at the project root.
"skipLibCheck": true skips type-checking dependency declaration files. This is also a default setting in tsconfig.json generated by npx tsc --init. With SDK 3.5.0 and TypeScript 7, omitting this causes an error in the SDK’s own declarations that your code cannot fix.

The SDK is published as ES modules and bundles its own types: no @types/ package is needed for it. If your editor lacks auto-completion, the issue lies in your tsconfig.json, not a missing types package.

Configure the Environment Variable

Never hard-code the API key in your source code. In Node.js, the standard solution is dotenv, which loads variables from a local file at process startup:

npm install dotenv

Create a .env file at your project root:

MISTRAL_API_KEY=your-api-key-here

Add this file to your .gitignore immediately, before your first commit. This is the exact moment keys leak:

.env
.env.local

The dotenv/config import must precede any reading of process.env. Otherwise, the variable remains undefined when you instantiate the client:

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

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

Verify the Installation

Before writing business logic, validate the entire chain—installation, key, network—with a minimal script. Create src/test-mistral.ts and simply request the list of models accessible to your account:

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

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

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

  for (const model of liste.slice(0, 5)) {
    // A model type unknown to this SDK version is marked 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

These two checks are not decorative. The SDK declares data optional, and each list entry is either a base model card, a fine-tuned model card, or an unknown value (type: 'UNKNOWN'). When the API adds a new model type, the SDK preserves it in this form instead of crashing. Without these two tests, strict mode refuses to compile.

In development, run it with tsx, installed earlier, which transpiles on the fly and saves you a build step:

npx tsx src/test-mistral.ts

Warning: tsx does not check types; it strips them and executes. Only tsc reports typing errors. Run npx tsc --noEmit to check without compiling. To compile then run, as your build pipeline will do:

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

A valid key displays the model count and the first five entries. A rejected key displays a Status 401 error (Invalid API Key): the chain works, only the key is at fault.

Organize the Project

Once verification passes, structure the project so the key and client do not scatter across files:

mon-projet/
├── src/
│   ├── index.ts          # Entry point
│   ├── mistral-client.ts # Client initialization (singleton)
│   └── utils/
├── .env                  # Environment variables (git-ignored)
├── .gitignore
├── package.json
└── tsconfig.json

Centralizing client initialization in a dedicated module avoids recreating it in every file. More importantly, it causes the application to fail at startup rather than on the first user call if the key is missing:

// 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,
});

The rest of the code simply imports this pre-built client:

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

Note the .js extension in the relative import. With module: nodenext, TypeScript requires the filename as it will exist after compilation, and tsx knows to map it to the .ts file. Import order also matters: dotenv/config executes before mistral-client.js, so the key is loaded when that module checks for its presence.

Key Takeaways

Install the TypeScript SDK with npm install @mistralai/mistralai
The main import is import { Mistral } from '@mistralai/mistralai'
Install typescript, tsx, and @types/node as development dependencies before calling npx tsc
Use module: nodenext and "type": "module" for code compiled then run by Node.js; relative imports take the .js extension
Use a .env file with dotenv to manage the API key
The SDK provides native TypeScript types: leverage auto-completion, and let tsc check what tsx skips
Centralize client initialization in a dedicated module