Instalación del SDK de TypeScript de Mistral
En esta página
Lección actualizada el 3 de noviembre de 2026 tras ejecutar los ejemplos con el SDK
@mistralai/mistralai3.5.0 y TypeScript 7.0.2. La versión original no compilaba. Ejecutarnpx tscsin tener TypeScript instalado descarga el paquete npmtscabandonado (versión 2.0.4) en lugar del compilador. El script de prueba se encontraba fuera de la carpetasrcdeclarada entsconfig.json. El objetoprocesssolo se reconoce con@types/node. Por último, el modo estricto rechazamodels.data.lengthymodel.idsin una validación previa. El archivotsconfig.jsonsigue ahora el escenario «compilar y luego ejecutar con Node.js» de la guía de TypeScript, y las versiones 18 y 20 de Node.js, que han llegado al final de su vida útil, ya no se listan como suficientes. Fuentes: Descargar TypeScript · Elección de opciones del compilador (TypeScript) · Cambios en TypeScript 6.0 · tsx y TypeScript · Entornos de ejecución compatibles con el SDK · Calendario de lanzamientos de Node.js.
¿Por qué usar el SDK de TypeScript?
Si tu pila tecnológica se basa en Node.js, Deno o Bun, el SDK de TypeScript de Mistral te permite integrar modelos directamente en tus aplicaciones de JavaScript y TypeScript. Evitas capas intermedias en Python o tener que escribir llamadas HTTP personalizadas. Este es el escenario más común al añadir IA a una aplicación web existente: una API de Express, un backend de Next.js o un worker de Node que procesa una cola de mensajes.
El tipado estático de TypeScript añade una red de seguridad que compensa la inversión desde la primera hora de desarrollo. Tu editor completa los nombres de los parámetros en lugar de hacerte adivinar entre maxTokens y max_tokens; los errores de mayúsculas y minúsculas o los campos inventados saltan en tiempo de compilación, no en producción a las 3 de la mañana; y la documentación de los parámetros aparece al pasar el cursor sin salir del archivo. Esta red de seguridad es aún más importante porque las respuestas de la API son objetos anidados donde es fácil perder un nivel.
Prerrequisitos
El SDK está dirigido a las versiones LTS mantenidas de Node.js. A fecha de 3 de noviembre de 2026, estas son las versiones 22, 24 y 26; Node.js 18 y 20 ya no reciben parches de seguridad. Comprueba tu versión con node --version antes de continuar: el SDK depende de los módulos ES y de la API nativa fetch. También necesitas un gestor de paquetes (npm, yarn o pnpm) y una clave de API de Mistral creada y disponible como variable de entorno, tal como se explicó en lecciones anteriores.
Instalación
El SDK oficial se publica en npm como @mistralai/mistralai:
# Con npm
npm install @mistralai/mistralai
# Con yarn
yarn add @mistralai/mistralai
# Con pnpm
pnpm add @mistralai/mistralai
Configuración de TypeScript
Si usas TypeScript —lo cual recomendamos—, instala tres herramientas como dependencias de desarrollo: el compilador, tsx (que ejecuta archivos .ts sin paso de compilación) y @types/node (que describe objetos de Node.js como process para TypeScript):
npm install -D typescript tsx @types/node
No te saltes este paso. Sin TypeScript instalado en el proyecto, npx tsc obtiene el paquete tsc de npm —un compilador heredado abandonado (2.0.4)— en lugar de TypeScript. A continuación, declara el proyecto como módulos ES, tal como exige la documentación de TypeScript para el código que se compila y luego es ejecutado por Node.js:
npm pkg set type=module
Por último, crea tsconfig.json. Utiliza la configuración que la guía oficial de TypeScript recomienda para este escenario (module: nodenext). También activa el modo estricto, que te obliga a gestionar valores potencialmente faltantes en las respuestas de la API —una restricción saludable— y compila src/ en dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tres líneas merecen una explicación, ya que cada una previene un error que encontramos al probar esta lección:
"types": ["node"]carga los tipos de Node.js. Desde TypeScript 6.0, los paquetes@typesya no se cargan automáticamente. Sin esta línea,process.envprovoca el error “Cannot find name ‘process’”, incluso con@types/nodeinstalado."rootDir": "src"establece la raíz de origen para los archivos compilados:src/test-mistral.tsse convierte endist/test-mistral.js. Sin ella, TypeScript 7 informa del error TS5011 siempre que tus fuentes no estén en la raíz del proyecto."skipLibCheck": trueomite la comprobación de tipos en los archivos de declaración de dependencias. Esta es también una configuración predeterminada entsconfig.jsongenerado pornpx tsc --init. Con el SDK 3.5.0 y TypeScript 7, omitir esto causa un error en las propias declaraciones del SDK que tu código no puede solucionar.
El SDK se publica como módulos ES e incluye sus propios tipos: no se necesita ningún paquete @types/ para él. Si tu editor carece de autocompletado, el problema reside en tu tsconfig.json, no en un paquete de tipos faltante.
Configuración de la variable de entorno
Nunca codifiques la clave de API directamente en tu código fuente. En Node.js, la solución estándar es dotenv, que carga las variables desde un archivo local al iniciar el proceso:
npm install dotenv
Crea un archivo .env en la raíz de tu proyecto:
MISTRAL_API_KEY=tu-clave-api-aquí
Añade este archivo a tu .gitignore inmediatamente, antes de tu primer commit. Este es el momento exacto en que se filtran las claves:
.env
.env.local
La importación dotenv/config debe preceder a cualquier lectura de process.env. De lo contrario, la variable permanecerá indefinida cuando instancies el cliente:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Verificación de la instalación
Antes de escribir la lógica de negocio, valida toda la cadena —instalación, clave, red— con un script mínimo. Crea src/test-mistral.ts y solicita simplemente la lista de modelos accesibles para tu cuenta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Listar modelos disponibles
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Modelos disponibles: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Un tipo de modelo desconocido para esta versión del SDK se marca como 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Estas dos comprobaciones no son decorativas. El SDK declara data como opcional, y cada entrada de la lista es una ficha de modelo base, una ficha de modelo ajustado (fine-tuned) o un valor desconocido (type: 'UNKNOWN'). Cuando la API añade un nuevo tipo de modelo, el SDK lo conserva en esta forma en lugar de fallar. Sin estas dos pruebas, el modo estricto se niega a compilar.
En desarrollo, ejecútalo con tsx, instalado anteriormente, que transpila al vuelo y te ahorra un paso de compilación:
npx tsx src/test-mistral.ts
Advertencia: tsx no comprueba los tipos; los elimina y ejecuta. Solo tsc informa de errores de tipado. Ejecuta npx tsc --noEmit para comprobar sin compilar. Para compilar y luego ejecutar, como hará tu pipeline de construcción:
npx tsc && node dist/test-mistral.js
Una clave válida muestra el recuento de modelos y las primeras cinco entradas. Una clave rechazada muestra un error Status 401 (Invalid API Key): la cadena funciona, solo la clave es incorrecta.
Organización del proyecto
Una vez superada la verificación, estructura el proyecto para que la clave y el cliente no se dispersen por los archivos:
mon-projet/
├── src/
│ ├── index.ts # Punto de entrada
│ ├── mistral-client.ts # Inicialización del cliente (singleton)
│ └── utils/
├── .env # Variables de entorno (ignoradas por git)
├── .gitignore
├── package.json
└── tsconfig.json
Centralizar la inicialización del cliente en un módulo dedicado evita recrearlo en cada archivo. Más importante aún, hace que la aplicación falle al inicio en lugar de en la primera llamada del usuario si falta la clave:
// src/mistral-client.ts
import { Mistral } from '@mistralai/mistralai';
if (!process.env.MISTRAL_API_KEY) {
throw new Error('La variable MISTRAL_API_KEY es obligatoria.');
}
export const mistral = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
El resto del código simplemente importa este cliente preconfigurado:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Observa la extensión .js en la importación relativa. Con module: nodenext, TypeScript requiere el nombre del archivo tal como existirá tras la compilación, y tsx sabe cómo mapearlo al archivo .ts. El orden de importación también importa: dotenv/config se ejecuta antes que mistral-client.js, por lo que la clave se carga cuando ese módulo comprueba su presencia.
Puntos clave
- Instala el SDK de TypeScript con
npm install @mistralai/mistralai - La importación principal es
import { Mistral } from '@mistralai/mistralai' - Instala
typescript,tsxy@types/nodecomo dependencias de desarrollo antes de llamar anpx tsc - Usa
module: nodenexty"type": "module"para código compilado y luego ejecutado por Node.js; las importaciones relativas llevan la extensión.js - Usa un archivo
.envcondotenvpara gestionar la clave de API - El SDK proporciona tipos nativos de TypeScript: aprovecha el autocompletado y deja que
tsccompruebe lo quetsxomite - Centraliza la inicialización del cliente en un módulo dedicado