Ir al contenido principal
Español— Elegir un idioma
Menú

Instalación del SDK de TypeScript de Mistral

Lección 8 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. ¿Por qué usar el SDK de TypeScript?
  2. Prerrequisitos
  3. Instalación
  4. Configuración de TypeScript
  5. Configuración de la variable de entorno
  6. Verificación de la instalación
  7. Organización del proyecto
  8. Puntos clave

Lección actualizada el 3 de noviembre de 2026 tras ejecutar los ejemplos con el SDK @mistralai/mistralai 3.5.0 y TypeScript 7.0.2. La versión original no compilaba. Ejecutar npx tsc sin tener TypeScript instalado descarga el paquete npm tsc abandonado (versión 2.0.4) en lugar del compilador. El script de prueba se encontraba fuera de la carpeta src declarada en tsconfig.json. El objeto process solo se reconoce con @types/node. Por último, el modo estricto rechaza models.data.length y model.id sin una validación previa. El archivo tsconfig.json sigue 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 @types ya no se cargan automáticamente. Sin esta línea, process.env provoca el error “Cannot find name ‘process’”, incluso con @types/node instalado.
  • "rootDir": "src" establece la raíz de origen para los archivos compilados: src/test-mistral.ts se convierte en dist/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": true omite la comprobación de tipos en los archivos de declaración de dependencias. Esta es también una configuración predeterminada en tsconfig.json generado por npx 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, tsx y @types/node como dependencias de desarrollo antes de llamar a npx tsc
  • Usa module: nodenext y "type": "module" para código compilado y luego ejecutado por Node.js; las importaciones relativas llevan la extensión .js
  • Usa un archivo .env con dotenv para gestionar la clave de API
  • El SDK proporciona tipos nativos de TypeScript: aprovecha el autocompletado y deja que tsc compruebe lo que tsx omite
  • Centraliza la inicialización del cliente en un módulo dedicado