DEV Community

Viraj Lakshitha Bandara
Viraj Lakshitha Bandara

Posted on

Stop Hardcoding AI Prompts: A Developer’s Guide to PromptCache

#ai #llm #tooling #typescript

Manage, version, and deploy your team’s AI prompts like code — with a TypeScript SDK, REST API, and a shared library that keeps everyone on the same page.

If you’ve been building AI-powered features for any length of time, you’ve hit this wall: prompts scattered across .env files, Notion docs, Slack threads, and inline strings buried in your codebase. Someone tweaks a system prompt in production — no review, no history, no rollback. A teammate asks “which version of that email prompt are we using?” and nobody knows.

PromptCache solves this. It’s a centralized prompt management platform — think GitHub for your AI prompts — with versioning, typed variables, team collaboration, and a TypeScript SDK that lets you fetch and invoke prompts directly in your app. No more hardcoded strings.

This guide walks you through everything from setup to production integration.

Table of Contents

  1. What is PromptCache?
  2. Core Concepts
  3. Getting Started
  4. Installing the SDK
  5. Fetching and Invoking Prompts
  6. Typed Variables in Practice
  7. Versioning and Rollbacks
  8. Scoped API Keys
  9. REST API Usage (curl examples)
  10. Real-World Example: AI Email Feature
  11. Team Workflow
  12. Community Gallery
  13. Join the Beta

What is PromptCache?

PromptCache is a prompt management platform built specifically for engineering teams shipping AI features. It gives you:

  • One Library — all prompts in a single searchable, filterable workspace
  • Versioning — GitHub-style snapshots for every update, with instant rollback
  • Typed Variables — define {{role}}, {{tone}}, {{recipient}} with types and defaults
  • Collaboration — invite teammates, manage roles, share knowledge
  • REST API & TypeScript SDK — invoke prompts directly from your app with scoped keys

The problem it solves is real: without a shared prompt library, teams rebuild the same work over and over — and get inconsistent AI outputs every time.

Core Concepts

Before diving into code, here are the three things you need to understand:

Prompts are versioned templates stored in your PromptCache workspace. Each prompt has a unique ID you reference from your code.

Variables are typed placeholders inside prompt templates, written as {{variable_name}}. They can be required (e.g. role: string) or optional with defaults (e.g. tone: string, default: "professional").

Invoke is the act of resolving a prompt — filling in all variables and returning the final, ready-to-use string. The SDK handles this with client.prompts.invoke().

Getting Started

1. Create your workspace

Head to promptcache.app and request access to the invite-only beta. Access is granted within 24 hours.

2. Create your first prompt

In the dashboard, create a new prompt. Write your template using {{variable}} syntax — variables are auto-detected instantly:

You are a {{role}} at {{company}}.
Write a {{tone}} email to {{recipient}}
about {{topic}}.
Keep it under {{max_words}} words.
Enter fullscreen mode Exit fullscreen mode

PromptCache auto-detects the variables and shows you a panel where you set types and defaults:

Variable Type Status Default
role string required —
company string required —
tone string optional “professional”
recipient string required —
topic string required —
max_words number optional 200

3. Publish a version

Click Publish to snapshot the current prompt. You’ll get a stable prompt-id to reference from your app. Every subsequent edit creates a new version — your running app keeps using the last published version until you explicitly update it.

Installing the SDK 

npm install @optiqlabs/promptcache-sdk
Enter fullscreen mode Exit fullscreen mode

The SDK is a full TypeScript client with typed responses and IntelliSense support. No hardcoded prompt strings in your codebase — ever.

Fetching and Invoking Prompts

Here’s the complete flow from initialization to resolved prompt string:

import { PromptCacheClient } from '@optiqlabs/sdk';

// Initialize once, reuse across your app
const client = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_API_KEY, // 'pk_live_...'
  baseUrl: 'https://api.promptcache.app',
});

// Invoke a prompt by ID, passing variable values
const result = await client.prompts.invoke('your-prompt-id', {
  role: 'Senior Engineer',
  company: 'Acme Corp',
  recipient: 'the product team',
  topic: 'the new deployment pipeline',
  tone: 'professional',
  max_words: 150,
});

// result.rendered → fully resolved prompt string, ready to send to any LLM
console.log(result.rendered);
Enter fullscreen mode Exit fullscreen mode

result.rendered is the fully hydrated prompt — pass it directly to OpenAI, Anthropic, Gemini, or any other LLM API.

Full integration with an LLM 

import { PromptCacheClient } from '@optiqlabs/sdk';
import Anthropic from '@anthropic-ai/sdk';

const promptCache = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_API_KEY,
  baseUrl: 'https://api.promptcache.app',
});

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function generateEmail(params: {
  role: string;
  company: string;
  recipient: string;
  topic: string;
}) {
  // 1. Fetch + resolve the prompt from PromptCache
  const { rendered } = await promptCache.prompts.invoke('email-generator-v2', {
    ...params,
    tone: 'professional',
    max_words: 200,
  });

  // 2. Send resolved prompt to your LLM of choice
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: rendered }],
  });

  return message.content[0].text;
}
Enter fullscreen mode Exit fullscreen mode

Now when your AI engineer improves the email prompt, they publish a new version in PromptCache — no code change, no redeployment needed. The app picks it up on the next invocation.

Typed Variables in Practice

Variables are the core of PromptCache’s power. Let’s look at how types and defaults work.

Required vs Optional

When you invoke a prompt, the SDK will surface TypeScript errors if you omit a required variable:

// ❌ TypeScript error: missing required variable 'role'
const result = await client.prompts.invoke('email-generator-v2', {
  company: 'Acme Corp',
  recipient: 'the board',
  topic: 'Q2 results',
});

// ✅ Correct — all required fields provided
const result = await client.prompts.invoke('email-generator-v2', {
  role: 'CFO',
  company: 'Acme Corp',
  recipient: 'the board',
  topic: 'Q2 results',
  // 'tone' and 'max_words' use their defaults
});
Enter fullscreen mode Exit fullscreen mode

Inject Mode for UI Forms

PromptCache’s Inject Mode identifies which variables are missing and returns them, making it trivial to build dynamic forms. If a user fills in a form and forgets a field, you can surface exactly what’s missing before making the API call.

const { missingVariables } = await client.prompts.getVariables('email-generator-v2');
// → ['role', 'recipient', 'topic']
// Use this to render the right form fields dynamically
Enter fullscreen mode Exit fullscreen mode

Versioning and Rollbacks

Every time you publish a prompt in PromptCache, a snapshot is created — like a Git commit. This means:

  • You always know what prompt your production app is running
  • You can roll back to any previous version instantly from the dashboard
  • Your team can review prompt diffs before publishing

Pinning a specific version

By default, invoke() uses the latest published version. You can also pin to a specific version:

// Pin to a specific published version
const result = await client.prompts.invoke('email-generator-v2', variables, {
  version: '3', // use version 3 specifically
});
Enter fullscreen mode Exit fullscreen mode

This is useful for A/B testing different prompt versions, or for gradually rolling out a new prompt.

Scoped API Keys

PromptCache uses scoped API keys — you don’t hand out a single master key to every service. Instead, you create purpose-specific keys:

Scope What it can do
read Fetch and invoke prompts
write Create and update prompts
org:read Read all prompts across the org

For a production app that only invokes prompts, create a read-scoped key. This limits blast radius if a key leaks.

// Production service — read-only key
const client = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_READ_KEY, // 'pk_live_read_...'
  baseUrl: 'https://api.promptcache.app',
});
Enter fullscreen mode Exit fullscreen mode

Manage and rotate keys from the Settings → API Keys panel in your workspace.

REST API Usage

If you’re not using TypeScript, or you’re in a backend language like Python, Go, or Ruby, the REST API has you covered.

Invoke a prompt via curl 

curl -X POST https://api.promptcache.app/v1/prompts/email-generator-v2/invoke \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "role": "Senior Engineer",
      "company": "Acme Corp",
      "recipient": "the product team",
      "topic": "the new CI pipeline",
      "tone": "professional",
      "max_words": 150
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "promptId": "email-generator-v2",
  "version": "4",
  "rendered": "You are a Senior Engineer at Acme Corp. Write a professional email to the product team about the new CI pipeline. Keep it under 150 words.",
  "variables": {
    "role": "Senior Engineer",
    "company": "Acme Corp",
    "recipient": "the product team",
    "topic": "the new CI pipeline",
    "tone": "professional",
    "max_words": 150
  }
}
Enter fullscreen mode Exit fullscreen mode

Fetch prompt metadata 

curl https://api.promptcache.app/v1/prompts/email-generator-v2 \
  -H "Authorization: Bearer pk_live_..."
Enter fullscreen mode Exit fullscreen mode

For full API reference, visit docs.promptcache.app.

Real-World Example

AI Email Feature (Next.js API Route)

Let’s put it all together. Here’s a Next.js API route that powers an AI email drafting feature:

// app/api/draft-email/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { PromptCacheClient } from '@optiqlabs/sdk';
import Anthropic from '@anthropic-ai/sdk';

const promptCache = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_API_KEY!,
  baseUrl: 'https://api.promptcache.app',
});

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

export async function POST(req: NextRequest) {
  const { role, company, recipient, topic, tone, maxWords } = await req.json();

  // Validate required fields
  if (!role || !company || !recipient || !topic) {
    return NextResponse.json(
      { error: 'Missing required fields' },
      { status: 400 }
    );
  }

  try {
    // Step 1: Resolve the prompt from PromptCache
    const { rendered, version } = await promptCache.prompts.invoke(
      'email-generator-v2',
      {
        role,
        company,
        recipient,
        topic,
        tone: tone ?? 'professional',
        max_words: maxWords ?? 200,
      }
    );

    // Step 2: Send to LLM
    const message = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: rendered }],
    });

    const draft = message.content[0].type === 'text'
      ? message.content[0].text
      : '';

    return NextResponse.json({
      draft,
      promptVersion: version, // useful for debugging / audit logs
    });
  } catch (err) {
    console.error('PromptCache or LLM error:', err);
    return NextResponse.json(
      { error: 'Failed to generate email' },
      { status: 500 }
    );
  }
}
Enter fullscreen mode Exit fullscreen mode

Notice that promptVersion is returned to the client — you can log this alongside every AI response to know exactly which prompt version produced each output. This is invaluable when debugging regressions.

Team Workflow

Here’s how a typical team uses PromptCache day-to-day:

1. Create — An AI engineer writes a prompt template with {{variables}}, which are auto-detected. They set required fields and sensible defaults.

2. Publish — They snapshot a version, share it in the gallery (public or private), or hand off the prompt ID to the engineering team.

3. Integrate — A developer drops client.prompts.invoke('prompt-id', variables) into the app. No hardcoded strings.

4. Track — The team monitors usage, API key activity, and audit logs from the dashboard. They can see which prompt versions are getting the most invocations.

5. Iterate — Someone improves the prompt. They publish a new version. The app picks it up automatically — zero redeployment.

Additional team features:

  • Bulk CSV Import — migrate your existing prompt library in one shot
  • Admin Safeguards — role-based access controls to prevent accidental overwrites
  • Open-in-AI Deep Links — one-click to pre-fill ChatGPT, Claude, or Gemini for quick testing

Community Gallery

PromptCache includes a public gallery where teams can share prompt templates. Each gallery card shows the prompt’s variables, a category tag, and two actions:

  • Copy — grab the prompt as-is
  • Fork — copy it into your own workspace and customize it

The gallery already includes templates like Cold Email Generator ({{company}}, {{pain_point}}, {{your_solution}}), Code Review Assistant ({{language}}, {{review_type}}), and Blog Post Outline ({{format}}, {{topic}}, {{audience}}).

This means your team doesn’t start from a blank slate — you fork a battle-tested community prompt, customize the variables for your use case, and ship faster.

When Should You Use PromptCache?

PromptCache is the right choice when:

  • You have more than one developer touching AI prompts (coordination problem)
  • You’re iterating on prompts regularly and need history + rollback
  • You want to separate prompt content from application code (no redeploys for prompt tweaks)
  • You need audit logs — compliance, debugging, or customer success teams asking “what prompt generated this output?”
  • You’re building multi-tenant apps where prompt variables change per customer

It’s less critical for solo projects with a single, static system prompt — though even there, versioning pays dividends the moment you want to experiment.

Join the Beta

PromptCache is currently in invite-only beta. Beta access is granted within 24 hours of your request.

Wrapping Up

The prompt is the most important part of your AI feature — it deserves the same engineering discipline as your application code. PromptCache brings versioning, typed variables, collaboration, and a clean SDK to prompt management, so your team ships faster and with more confidence.

Key takeaways:

  • Install with npm install @optiqlabs/promptcache-sdk
  • Initialize PromptCacheClient once with your scoped API key
  • Call client.prompts.invoke('prompt-id', variables) and get back result.rendered
  • Pass that string directly to any LLM — no prompt logic lives in your codebase
  • Iterate on prompts in the dashboard, publish new versions, and your app updates without a redeploy

If you’re building AI features for a team, give PromptCache a try. The “which version did you use?” question should never come up again.

Have questions or built something cool with PromptCache? Drop a comment below.

Tags: #ai #devtools #typescript #llm #promptengineering #openai #anthropic #javascript #webdev #programming

Top comments (0)