Groq Local Dev Loop

Groq Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Groq. Groq's sub-second response times make it uniquely suited for tight dev loops -- you get LLM responses fast enough to iterate without context-switching. This skill scaffolds a project, a memoized client, model constants, and a two-tier test strategy (mocked unit tests + opt-in live integration tests). The lean skeleton lives here; the full code lives in references/implementation.md and references/examples.md.

Prerequisites

• groq-sdk installed (npm install groq-sdk)
• GROQ_API_KEY set (free tier is fine for development)
• Node.js 18+ with tsx for TypeScript execution
• vitest for testing

Authentication

The groq-sdk client reads GROQ_API_KEY from the environment automatically — new Groq() and getGroqClient() both pick it up. Get a key at console.groq.com/keys, store it in a git-ignored .env.local, and commit only .env.example as a template. Never hardcode the key or commit .env.local.

Instructions

Follow these seven steps in order. Steps 1-2 lay out the project; steps 3-4 centralize the client and model IDs; steps 5-6 establish the test tiers; step 7 templates the environment. Full code for each is in the reference files.

1. Project structure — create src/groq/{client,models,completions}.ts, tests/, and .env.local / .env.example.
2. Package setup — wire dev (tsx watch), test / test:watch (vitest), and test:integration scripts.
3. Singleton client — a lazily-memoized getGroqClient() that fails fast when GROQ_API_KEY is missing and a resetClient() for tests.
4. Model constants — a MODELS map with DEV_MODEL defaulting to llama-3.1-8b-instant to conserve dev quota.
5. Unit tests with mocking — vi.mock("groq-sdk") so unit tests run sub-second with zero API calls.
6. Integration tests — guard live-API tests behind GROQ_INTEGRATION=1 with describe.skipIf so the default run stays offline.
7. Environment template — commit .env.example, git-ignore .env.local.

// src/groq/client.ts -- lazily-memoized singleton
import Groq from "groq-sdk";

let _client: Groq | null = null;