​
Overview

Prompt references (Snippets) allow you to modularize your prompts by referencing other prompts within your project. This feature is particularly useful for:
  • Managing large projects with reusable prompt components.
  • Reducing duplication by reusing common sections (e.g., policies, instructions).
  • Simplifying maintenance by centralizing updates to shared prompts.

​
Syntax

To reference another prompt, use the <prompt path="..." /> tag. The path attribute specifies the relative or absolute path to the referenced prompt.

​
Basic Usage

Referenced prompts are isolated from the parent prompt by default, meaning they don’t inherit variables. However, you can pass variables explicitly using attributes in the <prompt> tag. 
<prompt path="policies" assistant_name={{ assistant_name }} />

<user>{{ user_question }}</user>
In this example:
  1. The parent prompt references policies.promptl and passes the assistant_name variable.
  2. The assistant_name variable is interpolated in the referenced prompt.

​
Setup

Prompt references are not enabled by default. Since PropmtL does not know how your prompts are structured, you must provide a referenceFn function to define how PromptL should locate and load referenced prompts. You can structure your prompts in any way you like, as long as your referenceFn can find and load them. Some examples include:
  • Storing prompts in a file system.
  • Using a database to store prompts.
  • Fetching prompts from an API.

​
Basic referenceFn

Create a function that retrieves a prompt based on its path: 
import fs from 'fs';

function getPrompt(path) {
  return fs.readFileSync(path, 'utf8');
}

​
Supporting Relative Paths

To resolve paths relative to the current prompt, you can define a second argument with the current prompt’s full path: 
import path from 'path';
import fs from 'fs';

function getPrompt(relativePath, currentPath) {
  const fullPath = path.resolve(path.dirname(currentPath), relativePath);
  return fs.readFileSync(fullPath, 'utf8');
}

​
Using the referenceFn

Pass your referenceFn to the render function: 
import { render } from 'promptl-ai';
import getPrompt from './getPrompt'; // Import your custom resolve function

const { messages, config } = await render({
  prompt: mainPrompt, // Your main PromptL prompt as a string
  referenceFn: getPrompt, // Provide the resolve function
});
Tip: Prompts can be stored in files, a database, or any structured format. Adapt referenceFn to fit your storage solution.

​
Real-World Examples

​
Modular Prompts for Instructions

<prompt path="instructions" assistant_name="HelperBot" />

<user>
  What can you do for me?
</user>

​
Nested References

Prompts can reference other prompts, enabling complex workflows. 
<prompt path="policies" />
<prompt path="faq" />

​
Best Practices

  1. Use Descriptive Paths:
    • Organize prompts logically (e.g., prompts/policies.promptl).
  2. Centralize Shared Logic:
    • Store common instructions, rules, or templates in reusable prompts.
  3. Pass Variables Explicitly:
    • Always pass required variables to avoid missing or mismatched data.
  4. Avoid Circular References:
    • Ensure prompts don’t reference each other in loops.

​
Debugging Tips

If your prompt references aren’t working as expected:
  1. Check File Paths:
    • Ensure path in the <prompt> tag matches the actual file structure.
  2. Log Resolved Prompts:
    • Add a console.log() in referenceFn to verify the correct prompt is being loaded.
  3. Handle Missing Prompts:
    • Add error handling in referenceFn to handle missing or unreadable prompts gracefully:
    function getPrompt(path) {
  try {
    return fs.readFileSync(path, 'utf8');
  } catch (error) {
    console.error(`Error loading prompt: ${path}`);
    throw error;
  }
}
  4. Inspect Variables:
    • Confirm that required variables are being passed correctly.

​
Summary

Prompt references enable modular and maintainable prompt structures by allowing you to reuse and manage shared sections across projects. With features like variable passing, nested references, and customizable resolution logic, PromptL makes it easy to handle even the largest and most complex prompt configurations.