Skip to content
PromptlyCMS PromptlyCMS

Type Generation

The promptly generate CLI command fetches all your prompts from the API and generates a TypeScript declaration file with typed template variables for every prompt ID.

Run codegen

Section titled “Run codegen”
Terminal window
bunx promptly generate

This generates a promptly-env.d.ts declaration file. The CLI automatically places it in src/types/ or types/ if either directory exists in your project, otherwise it falls back to the project root.

Generated output

Section titled “Generated output”

The generated file uses declaration merging to augment the PromptVariableMap interface:

promptly-env.d.ts
// Auto-generated by @promptlycms/prompts - do not edit
import '@promptlycms/prompts';


declare module '@promptlycms/prompts' {
  interface PromptVariableMap {
    'review-prompt': {
      [V in 'latest' | '2.0.0' | '1.0.0']: {
        pickupLocation: string;
        items: string;
      };
    };
    'welcome-email': {
      [V in 'latest' | '1.0.0']: {
        email: string;
        subject: string;
      };
    };
  }
}

What this gives you

Section titled “What this gives you”

With the generated file present, you get:

  • Prompt ID autocomplete - getPrompt(' suggests all known prompt IDs
  • Typed template variables - result.userMessage({ ... }) only accepts the correct variable keys
  • Version-aware types - different versions can have different variables, and the types track this
  • Fallback for unknown IDs - untyped prompt IDs fall back to Record<string, string>

Before codegen

Section titled “Before codegen”
// No autocomplete, no type checking on variables
const result = await promptly.getPrompt('review-prompt');
result.userMessage({ anything: 'goes' }); // No error

After codegen

Section titled “After codegen”
// Autocomplete for prompt ID and variables
const result = await promptly.getPrompt('review-prompt');


result.userMessage({
  pickupLocation: 'London', // Typed
  items: 'sofa',            // Typed
});


result.userMessage({
  wrong: 'key', // Type error
});

Output location

Section titled “Output location”

By default, the CLI auto-detects the best location for the generated file:

PriorityDirectoryOutput path
1src/types/ existssrc/types/promptly-env.d.ts
2types/ existstypes/promptly-env.d.ts
3Fallback./promptly-env.d.ts

To override, use the --output (-o) flag:

Terminal window
npx promptly generate --output ./custom/path/promptly-env.d.ts

Pass API key directly

Section titled “Pass API key directly”

If you don’t have PROMPTLY_API_KEY set in your environment:

Terminal window
npx promptly generate --api-key pk_live_...

Best practices

Section titled “Best practices”
  • Re-run codegen whenever you add, remove, or rename template variables in the CMS
  • Commit the generated file so types are available without running codegen
  • Add to your build script if you want to always regenerate on deploy

How it works

Section titled “How it works”

Under the hood, promptly generate:

  1. Reads PROMPTLY_API_KEY from the environment (or --api-key flag)
  2. Calls GET /prompts?include_versions=true to fetch all prompts
  3. Extracts ${variable} template patterns from each prompt’s userMessage
  4. Groups versions with identical variables together
  5. Writes a declare module '@promptlycms/prompts' augmentation file

The PromptVariableMap interface is intentionally empty in the source package - it exists only as a declaration merging target. This is the same pattern used by Prisma and GraphQL Code Generator.

Next steps

Section titled “Next steps”