Agent Skills: 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;

export function getGroqClient(): Groq {
  if (!_client) {
    if (!process.env.GROQ_API_KEY) {
      throw new Error("GROQ_API_KEY not set. Copy .env.example to .env.local");
    }
    _client = new Groq({ apiKey: process.env.GROQ_API_KEY, maxRetries: 2, timeout: 30_000 });
  }
  return _client;
}
export function resetClient(): void { _client = null; }

See references/implementation.md for the full project scaffold, package.json, model constants, and .env.example, and references/examples.md for the complete unit and integration test files.

Output

Applying the workflow produces:

• A scaffolded project with src/groq/{client,models,completions}.ts and a tests/ directory.
• A memoized getGroqClient() that shares one configured client and throws an actionable error when GROQ_API_KEY is unset.
• A MODELS map + DEV_MODEL constant so dev runs on the cheap 8B model.
• A two-tier test suite: mocked unit tests (npm run test:watch, no API calls) and opt-in live tests (npm run test:integration, gated on GROQ_INTEGRATION=1).
• A .env.example template committed for the team, with real secrets in a git-ignored .env.local.

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | GROQ_API_KEY not set | Missing .env.local | Copy from .env.example | | Test timeout | Live API call in unit test | Mock groq-sdk in unit tests | | 429 rate_limit_exceeded | Free tier RPM hit | Wait 60s or use test:watch with longer intervals | | Port already in use | Another tsx watch running | Kill process or change port |

Dev Tips

• Use llama-3.1-8b-instant during development (lowest quota usage, fastest).
• Set temperature: 0 for deterministic outputs during debugging.
• Set max_tokens conservatively to avoid burning through free tier.
• Groq free tier: 30 RPM for 70B and 8B models -- plan your dev loops accordingly.

Examples

Run the hot-reload app and the mocked unit-test watcher side by side, then exercise the live API only when you opt in:

npm run dev                # tsx watch src/index.ts (hot reload)
npm run test:watch         # vitest --watch (mocked, no API calls)
npm run test:integration   # GROQ_INTEGRATION=1 vitest (live API)

For the complete mocked unit test (vi.mock("groq-sdk")) and the GROQ_INTEGRATION-gated live integration test, see references/examples.md.

Resources

• references/implementation.md — full project scaffold, client, model constants, and env template.
• references/examples.md — complete unit and integration test files.
• groq-sdk npm
• Vitest Documentation
• tsx Documentation
• For production-ready code patterns, see the groq-sdk-patterns skill.