superprompts

Official Node.js / TypeScript SDK for SuperPrompts: fetch versioned system prompts at runtime instead of hardcoding them. Zero dependencies, works anywhere fetch exists (Node 18+, Bun, Deno, edge runtimes).

npm install superprompts

import { SuperPrompts } from 'superprompts';

const sp = new SuperPrompts({ apiKey: process.env.SUPERPROMPTS_API_KEY! });

const { prompt } = await sp.getPrompt('your-prompt-id', {
    variables: { customer: 'Ada' }
});
// prompt is the assembled system message with variables filled in

Reading prompts

await sp.getPrompt(id); // published (production) version
await sp.getPrompt(id, { version: 'latest' }); // newest saved version, for staging
await sp.getPrompt(id, { version: '18bab0e' }); // pin a version by hash prefix
await sp.getPrompt(id, { guard: false }); // without Prompt Guard appended
await sp.getPrompt(id, { variables, strict: true }); // throw if a variable is missing
await sp.listPrompts(); // every prompt in the project

getPrompt responses are cached in memory per prompt and version for cacheTtlMs (default 5000 ms).

Response

type SuperPromptsResponse = {
    id: string;
    name: string;
    description: string;
    prompt: string; // assembled system message
    sections: { id: string; title: string; content: string }[];
    tools?: ToolJsonSchema[]; // OpenAI-compatible function definitions
    variables: string[]; // {{ variables }} referenced by the prompt
    version: string; // content hash of the version served
    label: 'production' | 'latest' | 'version';
    production_version: string | null;
    created_at: string;
    updated_at: string;
};

With OpenAI

import OpenAI from 'openai';

const prompt = await sp.getPrompt('support-agent', { variables: { customer: user.name } });

const completion = await new OpenAI().chat.completions.create({
    model: 'gpt-5',
    messages: [
        { role: 'system', content: prompt.prompt },
        { role: 'user', content: 'I need help with my order' }
    ],
    tools: prompt.tools
});

With Anthropic

import Anthropic from '@anthropic-ai/sdk';

const prompt = await sp.getPrompt('support-agent');

const message = await new Anthropic().messages.create({
    model: 'claude-sonnet-5',
    max_tokens: 1024,
    system: prompt.prompt,
    messages: [{ role: 'user', content: 'I need help with my order' }]
});

With the Vercel AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const prompt = await sp.getPrompt('writing-assistant');

const { text } = await generateText({
    model: openai('gpt-5'),
    system: prompt.prompt,
    prompt: 'Write a technical blog post about prompt management'
});

Writing prompts

const created = await sp.createPrompt({
    name: 'Onboarding email',
    markdown: '# Role\nYou write {{ tone }} emails.'
});

await sp.updatePrompt(created.id, {
    sections: [{ title: 'Role', content: 'You write short emails.' }],
    message: 'tighten'
});

await sp.publishPrompt(created.id); // publish latest
await sp.publishPrompt(created.id, '18bab0e'); // or roll back to a version

Options

new SuperPrompts({
    apiKey: 'sp_...', // required
    baseUrl: 'https://superprompts.app',
    cacheTtlMs: 5000, // 0 disables caching
    guard: true, // append Prompt Guard to fetched prompts
    fetch: customFetch // optional fetch implementation
});

Helpers

import { compile, extractVariables } from 'superprompts';

extractVariables('Hi {{ name }}, {{ topic }}'); // ['name', 'topic']
compile('Hi {{ name }}', { name: 'Ada' }); // 'Hi Ada'

Errors

API failures throw SuperPromptsError with a status property and the server's message.

Closure-style API

import { createPromptInstance } from 'superprompts';

const getPrompt = createPromptInstance({ apiKey: process.env.SUPERPROMPTS_API_KEY! });
const prompt = await getPrompt('your-prompt-id');

Links

• SuperPrompts
• Documentation
• REST API reference
• MCP server for Claude Code and Cursor

License

MIT