Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Instaliraj Mistral TypeScript SDK

Lekcija 8 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Zašto koristiti TypeScript SDK?
  2. Preduvjeti
  3. Instalacija
  4. Konfiguracija TypeScripta
  5. Konfiguriraj varijablu okruženja
  6. Provjeri instalaciju
  7. Organiziraj projekt
  8. Ključne točke

Lekcija ažurirana 3. studenog 2026. nakon pokretanja primjera sa SDK-om @mistralai/mistralai verzije 3.5.0 i TypeScriptom 7.0.2. Izvorna verzija se nije kompajlirala. Pokretanje npx tsc bez instaliranog TypeScripta preuzima napušteni npm paket tsc (verzija 2.0.4) umjesto kompajlera. Test skripta se nalazila izvan mape src deklarirane u tsconfig.json. Objekt process prepoznat je samo uz @types/node. Konačno, strogi način (strict mode) odbija models.data.length i model.id bez prethodne validacije. tsconfig.json sada slijedi scenarij “kompajliraj pa pokreni s Node.js” iz vodiča za TypeScript, a Node.js 18 i 20, kojima je istekao životni vijek, više nisu navedeni kao dovoljni. Izvori: Preuzmi TypeScript · Odabir opcija kompajlera (TypeScript) · Promjene u TypeScriptu 6.0 · tsx i TypeScript · Podržana izvršna okruženja za SDK · Raspored izdanja Node.jsa.

Zašto koristiti TypeScript SDK?

Ako tvoj stack ovisi o Node.jsu, Denu ili Bunu, Mistral TypeScript SDK omogućuje ti izravnu integraciju modela u tvoje JavaScript i TypeScript aplikacije. Izbjegavaš međuslojeve u Pythonu ili pisanje prilagođenih HTTP poziva. Ovo je najčešći scenarij kada dodaješ AI u postojeću web aplikaciju: Express API, Next.js backend ili Node worker koji obrađuje red poruka.

Statičko tipiziranje TypeScripta dodaje sigurnosnu mrežu koja se isplati već u prvom satu razvoja. Tvoj uređivač dovršava nazive parametara umjesto da nagađaš između maxTokens i max_tokens; pogreške u velikim i malim slovima ili izmišljena polja okidaju se tijekom kompajliranja, a ne u produkciji u 3 ujutro; dokumentacija parametara pojavljuje se na lebdeći pokazivač bez napuštanja datoteke. Ova sigurnosna mreža još je važnija jer su odgovori API-ja ugniježđeni objekti u kojima je lako propustiti razinu.

Preduvjeti

SDK cilja održavane LTS verzije Node.jsa. Zaključno s 3. studenim 2026., to su verzije 22, 24 i 26; Node.js 18 i 20 više ne primaju sigurnosne zakrpe. Provjeri svoju verziju s node --version prije nastavka: SDK se oslanja na ES module i nativni fetch API. Također trebaš upravitelja paketa (npm, yarn ili pnpm) i Mistral API ključ kreiran i dostupan kao varijabla okruženja, kako je obrađeno u prethodnim lekcijama.

Instalacija

Službeni SDK objavljen je na npm-u kao @mistralai/mistralai:

# S npm-om
npm install @mistralai/mistralai

# S yarnom
yarn add @mistralai/mistralai

# S pnpm-om
pnpm add @mistralai/mistralai

Konfiguracija TypeScripta

Ako koristiš TypeScript – što preporučujemo – instaliraj tri alata kao razvojne ovisnosti: kompajler, tsx (koji pokreće .ts datoteke bez koraka izgradnje) i @types/node (koji TypeScriptu opisuje Node.js objekte poput process):

npm install -D typescript tsx @types/node

Nemoj preskočiti ovaj korak. Bez TypeScripta instaliranog u projektu, npx tsc dohvaća paket tsc s npm-a – napušteni legacy kompajler (2.0.4) – umjesto TypeScripta. Zatim, deklariraj projekt kao ES module, kako dokumentacija TypeScripta zahtijeva za kod koji se kompajlira, a zatim pokreće putem Node.jsa:

npm pkg set type=module

Konačno, kreiraj tsconfig.json. Koristi postavke koje službeni vodič za TypeScript preporučuje za ovaj scenarij (module: nodenext). Također omogućuje strogi način (strict mode), koji te prisiljava da rukuješ potencijalno nedostajućim vrijednostima u odgovorima API-ja – zdravo ograničenje – i kompajlira src/ u dist/:

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

Tri retka zaslužuju objašnjenje, jer svaki sprječava grešku na koju smo naišli tijekom testiranja ove lekcije:

  • "types": ["node"] učitava Node.js tipove. Od TypeScripta 6.0, paketi @types više se ne učitavaju automatski. Bez ovog retka, process.env izaziva grešku “Cannot find name ‘process’”, čak i s instaliranim @types/node.
  • "rootDir": "src" postavlja izvorni korijen za kompajlirane datoteke: src/test-mistral.ts postaje dist/test-mistral.js. Bez toga, TypeScript 7 prijavljuje grešku TS5011 kad god tvoji izvori nisu u korijenu projekta.
  • "skipLibCheck": true preskače provjeru tipova u deklaracijskim datotekama ovisnosti. Ovo je također zadana postavka u tsconfig.json generiranom s npx tsc --init. Sa SDK-om 3.5.0 i TypeScriptom 7, izostavljanje ovoga uzrokuje grešku u vlastitim deklaracijama SDK-a koju tvoj kod ne može popraviti.

SDK je objavljen kao ES modul i uključuje vlastite tipove: nije potreban nikakav paket @types/ za njega. Ako tvom uređivaču nedostaje automatsko dovršavanje, problem leži u tvom tsconfig.json, a ne u nedostajućem paketu tipova.

Konfiguriraj varijablu okruženja

Nikada ne hardkodiraj API ključ u izvornom kodu. U Node.jsu, standardno rješenje je dotenv, koji učitava varijable iz lokalne datoteke pri pokretanju procesa:

npm install dotenv

Kreiraj .env datoteku u korijenu svog projekta:

MISTRAL_API_KEY=tvoj-api-ključ-ovdje

Odmah dodaj ovu datoteku u svoj .gitignore, prije prvog commita. To je točan trenutak kada ključevi cure:

.env
.env.local

Uvoz dotenv/config mora prethoditi svakom čitanju process.env. Inače, varijabla ostaje nedefinirana kada instanciraš klijenta:

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

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

Provjeri instalaciju

Prije pisanja poslovne logike, validiraj cijeli lanac – instalaciju, ključ, mrežu – s minimalnom skriptom. Kreiraj src/test-mistral.ts i jednostavno zatraži popis modela dostupnih tvom računu:

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

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

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

  for (const model of liste.slice(0, 5)) {
    // Tip modela nepoznat ovoj verziji SDK-a označen je kao 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Ove dvije provjere nisu dekorativne. SDK deklarira data kao opcionalno, a svaki unos na popisu je ili osnovna kartica modela, kartica fino podešenog modela ili nepoznata vrijednost (type: 'UNKNOWN'). Kada API doda novi tip modela, SDK ga zadržava u ovom obliku umjesto da se sruši. Bez ove dvije provjere, strogi način odbija kompajliranje.

U razvoju, pokreni ga s tsx, instaliranim ranije, koji transpilira u letu i štedi ti korak izgradnje:

npx tsx src/test-mistral.ts

Upozorenje: tsx ne provjerava tipove; on ih uklanja i izvršava. Samo tsc prijavljuje greške tipiziranja. Pokreni npx tsc --noEmit za provjeru bez kompajliranja. Za kompajliranje pa pokretanje, kako će to raditi tvoj pipeline izgradnje:

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

Valjani ključ prikazuje broj modela i prvih pet unosa. Odbijeni ključ prikazuje grešku Status 401 (Invalid API Key): lanac radi, samo je ključ problematičan.

Organiziraj projekt

Kada provjera prođe, strukturiraj projekt tako da se ključ i klijent ne rasprše po datotekama:

mon-projet/
├── src/
│   ├── index.ts          # Ulazna točka
│   ├── mistral-client.ts # Inicijalizacija klijenta (singleton)
│   └── utils/
├── .env                  # Varijable okruženja (git-ignored)
├── .gitignore
├── package.json
└── tsconfig.json

Centraliziranje inicijalizacije klijenta u namjenski modul izbjegava njegovo ponovno kreiranje u svakoj datoteci. Još važnije, to uzrokuje da aplikacija zakaže pri pokretanju, a ne pri prvom pozivu korisnika, ako ključ nedostaje:

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

Ostatak koda jednostavno uvozi ovog unaprijed izgrađenog klijenta:

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

Obrati pažnju na .js ekstenziju u relativnom uvozu. S module: nodenext, TypeScript zahtijeva ime datoteke kakvo će postojati nakon kompajliranja, a tsx zna kako ga mapirati na .ts datoteku. Redoslijed uvoza također je bitan: dotenv/config izvršava se prije mistral-client.js, tako da je ključ učitan kada taj modul provjerava njegovu prisutnost.

Ključne točke

  • Instaliraj TypeScript SDK s npm install @mistralai/mistralai
  • Glavni uvoz je import { Mistral } from '@mistralai/mistralai'
  • Instaliraj typescript, tsx i @types/node kao razvojne ovisnosti prije pozivanja npx tsc
  • Koristi module: nodenext i "type": "module" za kod koji se kompajlira, a zatim pokreće putem Node.jsa; relativni uvozi uzimaju .js ekstenziju
  • Koristi .env datoteku s dotenv za upravljanje API ključem
  • SDK pruža nativne TypeScript tipove: iskoristi automatsko dovršavanje i dopusti tsc da provjeri ono što tsx preskače
  • Centraliziraj inicijalizaciju klijenta u namjenski modul