Node SDK

The superprompts package fetches prompts at runtime, fills in variables and caches reads. Zero dependencies; runs anywhere fetch exists (Node 18+, Bun, Deno, edge).

Installation

Install the SuperPrompts package using npm or yarn:

npm install superprompts

yarn add superprompts

Basic Usage

Import the package and create a client with your API key:

import { SuperPrompts } from 'superprompts';

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

// Published version, variables filled in
const { prompt, version } = await sp.getPrompt('<PROMPT_ID>', {
  variables: { customer: 'Ada' }
});

console.log(prompt);       // assembled system message
console.log(version.slice(0, 7)); // content hash that was served

API Reference

new SuperPrompts(options)

apiKey (string, required): project API key
baseUrl: API origin, default https://superprompts.app
cacheTtlMs: in-memory cache per prompt and version, default 5000; 0 disables
guard: append Prompt Guard to fetched prompts, default true
fetch: custom fetch implementation

sp.getPrompt(promptId, options?)

version: 'production' (default), 'latest' or a version hash / unique prefix
variables: values for {{ placeholders }}, applied to prompt and every section
strict: throw when a variable has no value (default false, placeholder left as-is)
guard: per-call override

Returns { id, name, description, prompt, sections, tools?, variables, version, label, production_version, created_at, updated_at }.

Write methods

sp.listPrompts(): every prompt in the project
sp.createPrompt({ name, description?, sections? | markdown?, publish? })
sp.updatePrompt(id, { sections? | markdown?, message?, publish? }): save a new version
sp.publishPrompt(id, version?): point production at a version (latest by default)
sp.clearCache(id?)

Helpers and errors

compile(text, variables, { strict }) and extractVariables(text) are exported for templates you keep elsewhere. API failures throw SuperPromptsError with a status and the server's message.

Examples

Express.js Integration

import express from 'express';
import { SuperPrompts } from 'superprompts';

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

app.get('/chat', async (req, res) => {
  try {
    // Get prompt
    const response = await sp.getPrompt('<PROMPT_ID>');
    // Use response.prompt with your AI model
    res.json({ prompt: response.prompt });
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch prompt' });
  }
});

app.listen(3000);

Next.js API Route

import { SuperPrompts } from 'superprompts';
import { NextResponse } from 'next/server';

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

export async function GET() {
  try {
    const response = await sp.getPrompt('<PROMPT_ID>');
    return NextResponse.json({ prompt: response.prompt });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch prompt' },
      { status: 500 }
    );
  }
}

With OpenAI

import { SuperPrompts } from 'superprompts';
import OpenAI from 'openai';

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

async function chat(userMessage: string) {
  // Get prompt
  const response = await sp.getPrompt('assistant');
  
  const completion = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: response.prompt },
      { role: 'user', content: userMessage }
    ]
  });
  
  return completion.choices[0].message.content;
}

Next Steps

Authentication

Learn how to get and use your API key

More Examples

See more integration examples and use cases

View examples