> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v1.latitude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt References

> Learn how to reference other prompts in PromptL

## 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.

<CodeGroup>
  ```tsx parent.promptl theme={null}
  <prompt path="policies" assistant_name={{ assistant_name }} />

  <user>{{ user_question }}</user>
  ```

  ```plaintext policies.promptl theme={null}
  You are {{ assistant_name }}, an AI assistant created to help users.

  Before answering any questions, follow these rules:
  - Be respectful.
  - Avoid sharing personal information.
  - Use appropriate language.
  ```
</CodeGroup>

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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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>
  **Tip**: Prompts can be stored in files, a database, or any structured format. Adapt `referenceFn` to fit your storage solution.
</Tip>

***

## Real-World Examples

### Modular Prompts for Instructions

<CodeGroup>
  ```xml main.promptl theme={null}
  <prompt path="instructions" assistant_name="HelperBot" />

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

  ```xml instructions.promptl theme={null}
  You are {{ assistant_name }}, an assistant trained to provide technical support.

  Capabilities:
  - Debugging code.
  - Explaining concepts.
  - Recommending resources.
  ```
</CodeGroup>

***

### Nested References

Prompts can reference other prompts, enabling complex workflows.

<CodeGroup>
  ```xml main.promptl theme={null}
  <prompt path="policies" />
  <prompt path="faq" />
  ```

  ```xml policies.promptl theme={null}
  <prompt path="instructions" assistant_name="FAQBot" />

  <user>
    What are your rules?
  </user>
  ```
</CodeGroup>

***

## 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:
   ```javascript theme={null}
   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.