Fetching Composers

A composer is a document template that combines static HTML segments with prompt references. getComposer() fetches a composer, interpolates your variables, and resolves AI models. Then compose() runs every prompt in parallel and assembles the final output — all in one line.

Quick example

import { createPromptlyClient } from '@promptlycms/prompts';
import { generateText } from 'ai';

const promptly = createPromptlyClient();

const { compose } = await promptly.getComposer('article-composer', {
  input: { topic: 'TypeScript', audience: 'developers' },
});

// One line — runs all prompts in parallel and assembles the output
const output = await compose(generateText);

How it works

1. Fetch — getComposer() calls the Promptly API and gets the composer’s segment array
2. Interpolate — Template variables (${var} in prompts, {{var}} in static HTML) are replaced with your input values
3. Resolve models — Each prompt segment’s model is resolved to an AI SDK LanguageModel
4. Compose — compose() passes each prompt to your generate function, runs them in parallel via Promise.all, and assembles the static HTML + AI text into a single string

Per-prompt overrides

Pass a wrapper function to customise parameters for every prompt:

const output = await compose((prompt) =>
  generateText({ ...prompt, maxTokens: 500 })
);

The prompt argument has the shape { model, system, prompt, temperature, promptId, promptName }, so you can spread it and override individual fields.

Accessing metadata

const composer = await promptly.getComposer('my-composer', {
  input: { text: 'Hello world', targetLang: 'French' },
});

composer.composerId;   // 'my-composer'
composer.composerName; // 'My Composer'
composer.version;      // '1.0.0'
composer.config;       // { schema, inputData, inputDataRootName }
composer.segments;     // raw segment array from the API

Version pinning

By default, getComposer() fetches the latest published version. Pin to a specific version:

const { compose } = await promptly.getComposer('my-composer', {
  version: '2.0.0',
  input: { text: 'Hello world' },
});

Tip

Version pinning is useful for production deployments where you want to lock to a known-good composer version while iterating on a new version in the CMS.

Batch fetch

Use getComposers() to fetch multiple composers in parallel:

const [emailComposer, reportComposer] = await promptly.getComposers([
  { composerId: 'email-composer', input: { name: 'Alice' } },
  { composerId: 'report-composer', version: '2.0.0', input: { quarter: 'Q1' } },
]);

const emailOutput = await emailComposer.compose(generateText);
const reportOutput = await reportComposer.compose(generateText);

Real-world example

A Next.js API route that fetches a composer and returns the assembled document:

app/api/generate-report/route.ts

import { createPromptlyClient } from '@promptlycms/prompts';
import { generateText } from 'ai';

const promptly = createPromptlyClient();

export const POST = async (req: Request) => {
  const { companyName, quarter } = await req.json();

  const { compose } = await promptly.getComposer('quarterly-report', {
    input: { companyName, quarter },
  });

  const report = await compose(generateText);

  return new Response(report, {
    headers: { 'Content-Type': 'text/html' },
  });
};

Type generation

If you have run codegen, the input object is fully typed to the exact variables defined in the CMS. Without codegen, inputs fall back to Record<string, string>.

Next steps

• Need per-prompt control, streaming, or structured output? See Advanced Composer Patterns
• Explore AI SDK integration patterns for prompts
• Learn about model resolution and custom resolvers
• Handle errors from the API
• Create and version your composers in the Promptly CMS