{"id":10973,"library":"groq-sdk","title":"Groq API TypeScript SDK","description":"The `groq-sdk` package provides the official TypeScript library for interacting with the Groq API, offering convenient access to Groq's REST API from both server-side TypeScript and JavaScript environments. It is currently at stable version `1.1.2`, released on 2026-03-25. The library exhibits a rapid release cadence, with frequent minor versions and patches, often coinciding with updates to the underlying Groq API. Key differentiators include comprehensive TypeScript support with precise type definitions for all request parameters and response fields, ensuring a robust and type-safe development experience. The SDK is generated using Stainless and includes extensive documentation via docstrings. It supports various methods for file uploads, including `File` instances, `fs.ReadStream`, `fetch` `Response` objects, and a dedicated `toFile` helper for diverse environments.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/groq/groq-typescript","tags":["javascript","typescript"],"install":[{"cmd":"npm install groq-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add groq-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add groq-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary client is a default export. The library is primarily ESM-first, so CommonJS `require` is generally discouraged and may lead to issues.","wrong":"const Groq = require('groq-sdk');","symbol":"Groq","correct":"import Groq from 'groq-sdk';"},{"note":"Type definitions are nested under the `Groq` namespace, allowing direct access like `Groq.Chat.ChatCompletion` or `Groq.Chat.CompletionCreateParams` after importing the main client.","symbol":"Groq.Chat.CompletionCreateParams","correct":"import Groq from 'groq-sdk';\n// ... then use Groq.Chat.CompletionCreateParams"},{"note":"The `toFile` utility is a named export, useful for converting various data sources into file-like objects for API uploads.","wrong":"import Groq, { toFile } from 'groq-sdk'; // Common but slightly less precise if only needing toFile","symbol":"toFile","correct":"import { toFile } from 'groq-sdk';"}],"quickstart":{"code":"import Groq from 'groq-sdk';\n\nconst client = new Groq({\n  apiKey: process.env['GROQ_API_KEY'] ?? '', // Ensure GROQ_API_KEY is set in your environment\n});\n\nasync function main() {\n  try {\n    const chatCompletion = await client.chat.completions.create({\n      messages: [\n        { role: 'system', content: 'You are a helpful assistant.' },\n        { role: 'user', content: 'Explain the importance of low latency LLMs' }\n      ],\n      model: 'llama3-8b-8192', // Replace with a valid Groq model, e.g., 'llama3-8b-8192'\n      temperature: 0.7,\n      max_tokens: 1024\n    });\n\n    console.log(`Completion ID: ${chatCompletion.id}`);\n    console.log(`First choice message: ${chatCompletion.choices[0]?.message?.content}`);\n  } catch (error) {\n    if (error instanceof Groq.APIError) {\n      console.error(`API Error: ${error.status} - ${error.name}: ${error.message}`);\n      console.error('Headers:', error.headers);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n  }\n}\n\nmain();","lang":"typescript","description":"This quickstart initializes the Groq client with an API key from environment variables and sends a chat completion request to an LLM, including basic error handling for API-specific errors."},"warnings":[{"fix":"Thoroughly review the official migration guides and documentation for `v1.0.0` when upgrading from versions prior to `1.0.0`. Update import statements and object structures as necessary.","message":"Version `1.0.0` included a significant 'TS migration' which may introduce breaking changes, especially for users upgrading from pre-1.0.0 versions that might have relied on different internal structures or JavaScript-specific patterns. Review the `v1.0.0` changelog carefully for migration paths.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `process.env['GROQ_API_KEY']` is correctly set, or pass the `apiKey` property directly to the `Groq` client constructor: `new Groq({ apiKey: 'YOUR_API_KEY' })`.","message":"The Groq API key (GROQ_API_KEY) must be provided, either directly in the client configuration or via the `GROQ_API_KEY` environment variable. Failure to provide it will result in authentication errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use `import Groq from 'groq-sdk';` instead of `const Groq = require('groq-sdk');` for all module imports to ensure compatibility and correct type inference.","message":"This SDK primarily targets modern JavaScript/TypeScript environments that support ESM imports. While transpilers can handle CommonJS `require` for some cases, it's best practice to use `import` statements to avoid potential module resolution issues, especially with TypeScript types.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set the `GROQ_API_KEY` environment variable (e.g., `export GROQ_API_KEY='sk-...'`) or explicitly pass `apiKey: 'YOUR_SECRET_KEY'` to the `Groq` client constructor.","cause":"The Groq client was instantiated without a valid API key provided through `apiKey` in the constructor or the `GROQ_API_KEY` environment variable.","error":"Error: Missing API Key. Pass `apiKey` to the client constructor or set the `GROQ_API_KEY` environment variable."},{"fix":"Change your import statement from `const Groq = require('groq-sdk');` to `import Groq from 'groq-sdk';`.","cause":"Attempting to instantiate the `Groq` client using CommonJS `require` syntax in an environment expecting ESM (e.g., modern Node.js module types or bundlers).","error":"TypeError: Groq is not a constructor"},{"fix":"Verify that your `GROQ_API_KEY` is correct, active, and has the necessary permissions. Regenerate the key if necessary from the Groq console.","cause":"The provided API key is invalid or expired, leading to an authentication failure with the Groq API.","error":"API Error: 401 - UnauthorizedError"}],"ecosystem":"npm"}