feat(ai-groq): Add Groq adapter package

.changeset/free-impalas-doubt.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-groq': minor
+---
+
+Adds a new @tanstack/ai-groq package(minor release), a Groq AI adapter for TanStack AI.

examples/ts-react-chat/package.json

@@ -15,6 +15,7 @@
  "@tanstack/ai-client": "workspace:*",
  "@tanstack/ai-gemini": "workspace:*",
  "@tanstack/ai-grok": "workspace:*",
+ "@tanstack/ai-groq": "workspace:*",
  "@tanstack/ai-ollama": "workspace:*",
  "@tanstack/ai-openai": "workspace:*",
  "@tanstack/ai-openrouter": "workspace:*",

examples/ts-react-chat/src/lib/model-selection.ts

@@ -4,6 +4,7 @@ export type Provider =
  | 'gemini'
  | 'ollama'
  | 'grok'
+ | 'groq'
  | 'openrouter'
 
 export interface ModelOption {
@@ -91,6 +92,23 @@ export const MODEL_OPTIONS: Array<ModelOption> = [
  label: 'Ollama - SmolLM',
  },
 
+ // Groq
+ {
+ provider: 'groq',
+ model: 'llama-3.3-70b-versatile',
+ label: 'Groq - Llama 3.3 70B',
+ },
+ {
+ provider: 'groq',
+ model: 'meta-llama/llama-4-maverick-17b-128e-instruct',
+ label: 'Groq - Llama 4 Maverick',
+ },
+ {
+ provider: 'groq',
+ model: 'meta-llama/llama-4-scout-17b-16e-instruct',
+ label: 'Groq - Llama 4 Scout',
+ },
+
  // Grok
  {
  provider: 'grok',

examples/ts-react-chat/src/routes/api.tanchat.ts

@@ -11,6 +11,7 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 import { geminiText } from '@tanstack/ai-gemini'
 import { openRouterText } from '@tanstack/ai-openrouter'
 import { grokText } from '@tanstack/ai-grok'
+import { groqText } from '@tanstack/ai-groq'
 import type { AnyTextAdapter } from '@tanstack/ai'
 import {
  addToCartToolDef,
@@ -26,6 +27,7 @@ type Provider =
  | 'gemini'
  | 'ollama'
  | 'grok'
+ | 'groq'
  | 'openrouter'
 
 const SYSTEM_PROMPT = `You are a helpful assistant for a guitar store.
@@ -131,6 +133,13 @@ export const Route = createFileRoute('/api/tanchat')({
  adapter: grokText((model || 'grok-3') as 'grok-3'),
  modelOptions: {},
  }),
+ groq: () =>
+ createChatOptions({
+ adapter: groqText(
+ (model ||
+ 'llama-3.3-70b-versatile') as 'llama-3.3-70b-versatile',
+ ),
+ }),
  ollama: () =>
  createChatOptions({
  adapter: ollamaText((model || 'gpt-oss:120b') as 'gpt-oss:120b'),

examples/ts-react-chat/src/routes/index.tsx

@@ -264,19 +264,25 @@ function ChatPage() {
  [selectedModel.provider, selectedModel.model],
  )
 
- const { messages, sendMessage, isLoading, addToolApprovalResponse, stop } =
- useChat({
- connection: fetchServerSentEvents('/api/tanchat'),
- tools,
- body,
- onCustomEvent: (eventType, data, context) => {
- console.log(
- `[CustomEvent] ${eventType}`,
- data,
- context.toolCallId ? `(tool call: ${context.toolCallId})` : '',
- )
- },
- })
+ const {
+ messages,
+ sendMessage,
+ isLoading,
+ error,
+ addToolApprovalResponse,
+ stop,
+ } = useChat({
+ connection: fetchServerSentEvents('/api/tanchat'),
+ tools,
+ body,
+ onCustomEvent: (eventType, data, context) => {
+ console.log(
+ `[CustomEvent] ${eventType}`,
+ data,
+ context.toolCallId ? `(tool call: ${context.toolCallId})` : '',
+ )
+ },
+ })
  const [input, setInput] = useState('')
 
  /**
@@ -415,6 +421,12 @@ function ChatPage() {
  addToolApprovalResponse={addToolApprovalResponse}
  />
 
+ {error && (
+ <div className="mx-4 mt-2 p-3 bg-red-500/10 border border-red-500/30 rounded-lg text-red-400 text-sm">
+ {error.message}
+ </div>
+ )}
+
  <ChatInputArea>
  <div className="space-y-3">
  {isLoading && (

packages/typescript/ai-groq/README.md

@@ -0,0 +1,91 @@
+# @tanstack/ai-groq
+
+Groq adapter for TanStack AI
+
+## Installation
+
+```bash
+npm install @tanstack/ai-groq
+# or
+pnpm add @tanstack/ai-groq
+# or
+yarn add @tanstack/ai-groq
+```
+
+## Setup
+
+Get your API key from [Groq Console](https://console.groq.com) and set it as an environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_..."
+```
+
+## Usage
+
+### Text/Chat Adapter
+
+```typescript
+import { groqText } from '@tanstack/ai-groq'
+import { generate } from '@tanstack/ai'
+
+const adapter = groqText('llama-3.3-70b-versatile')
+
+const result = await generate({
+ adapter,
+ model: 'llama-3.3-70b-versatile',
+ messages: [
+ { role: 'user', content: 'Explain quantum computing in simple terms' },
+ ],
+})
+
+console.log(result.text)
+```
+
+### With Explicit API Key
+
+```typescript
+import { createGroqText } from '@tanstack/ai-groq'
+
+const adapter = createGroqText('llama-3.3-70b-versatile', 'gsk_api_key')
+```
+
+## Supported Models
+
+### Chat Models
+
+- `llama-3.3-70b-versatile` - Meta Llama 3.3 70B (131k context)
+- `llama-3.1-8b-instant` - Meta Llama 3.1 8B (131k context)
+- `meta-llama/llama-4-maverick-17b-128e-instruct` - Meta Llama 4 Maverick (vision)
+- `meta-llama/llama-4-scout-17b-16e-instruct` - Meta Llama 4 Scout
+- `meta-llama/llama-guard-4-12b` - Meta Llama Guard 4 (content moderation, vision)
+- `meta-llama/llama-prompt-guard-2-86m` - Meta Llama Prompt Guard (content moderation)
+- `meta-llama/llama-prompt-guard-2-22m` - Meta Llama Prompt Guard (content moderation)
+- `openai/gpt-oss-120b` - GPT OSS 120B (reasoning, tools, search)
+- `openai/gpt-oss-20b` - GPT OSS 20B (reasoning, search)
+- `openai/gpt-oss-safeguard-20b` - GPT OSS Safeguard 20B (content moderation, reasoning)
+- `moonshotai/kimi-k2-instruct-0905` - Kimi K2 Instruct (262k context)
+- `qwen/qwen3-32b` - Qwen3 32B (reasoning, tools)
+
+## Features
+
+- ✅ Streaming chat completions
+- ✅ Structured output (JSON Schema)
+- ✅ Function/tool calling
+- ✅ Multimodal input (text + images for vision models)
+- ❌ Embeddings (not supported by Groq)
+- ❌ Image generation (not supported by Groq)
+
+## Tree-Shakeable Adapters
+
+This package uses tree-shakeable adapters, so you only import what you need:
+
+```typescript
+// Only imports text adapter
+import { groqText } from '@tanstack/ai-groq'
+```
+
+This keeps your bundle size small!
+
+## License
+
+MIT

packages/typescript/ai-groq/package.json

@@ -0,0 +1,52 @@
+{
+ "name": "@tanstack/ai-groq",
+ "version": "0.0.0",
+ "type": "module",
+ "description": "Groq adapter for TanStack AI",
+ "author": "",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/TanStack/ai.git",
+ "directory": "packages/typescript/ai-groq"
+ },
+ "module": "./dist/esm/index.js",
+ "types": "./dist/esm/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/esm/index.d.ts",
+ "import": "./dist/esm/index.js"
+ }
+ },
+ "files": [
+ "dist",
+ "src"
+ ],
+ "scripts": {
+ "build": "vite build",
+ "clean": "premove ./build ./dist",
+ "lint:fix": "eslint ./src --fix",
+ "test:build": "publint --strict",
+ "test:eslint": "eslint ./src",
+ "test:lib": "vitest run",
+ "test:lib:dev": "pnpm test:lib --watch",
+ "test:types": "tsc"
+ },
+ "keywords": [
+ "ai",
+ "groq",
+ "tanstack",
+ "adapter"
+ ],
+ "devDependencies": {
+ "@vitest/coverage-v8": "4.0.14",
+ "vite": "^7.2.7"
+ },
+ "peerDependencies": {
+ "@tanstack/ai": "workspace:^",
+ "zod": "^4.0.0"
+ },
+ "dependencies": {
+ "groq-sdk": "^0.37.0"
+ }
+}