YAPL TypeScript

The official TypeScript implementation of YAPL (Yet Another Prompt Language) — a tiny, composable prompt templating language designed for AI agents.

Quick links: Website · Documentation · VS Code Extension · NPM Package · Discord

✨ Features

YAPL brings the power of modern templating to AI prompt engineering:

• 🧩 Template Inheritance — Build complex prompts by extending base templates
• 🔀 Mixins & Composition — Compose prompts from reusable components
• 🎯 Dynamic Variables — Use variables with default values for flexibility
• 🔀 Conditional Logic — Adapt prompts based on context and user types
• 📦 Modular Includes — Break large prompts into manageable pieces
• 🌐 Universal — Works in Node.js and browsers (ESM + CJS)
• ⚡ Fast — Optimized rendering with smart caching

🚀 Installation

# npm
npm install @yapl-language/yapl.ts

# pnpm
pnpm add @yapl-language/yapl.ts

# yarn
yarn add @yapl-language/yapl.ts

📝 Quick Start

💡 New to YAPL? Visit the website for an overview and try the interactive playground to experiment with templates in your browser. For comprehensive guides, check out the documentation.

Create your first YAPL template:

{# agent.md.yapl #}
{% extends "base/system.md.yapl" %}
{% mixin "mixins/friendly.md.yapl" %}

{% block persona %}
  You are {{ agent_name | default("a helpful AI assistant") }} specializing in {{ domain }}.
{% endblock %}

{% block guidance %}
  {{ super() }}
  {% if user_level == "beginner" %}
    Use simple language and provide step-by-step explanations.
  {% else %}
    You can use technical terminology and advanced concepts.
  {% endif %}
{% endblock %}

Render it with TypeScript:

// For Node.js environments
import { NodeYAPL } from "@yapl-language/yapl.ts";

// Single base directory (backwards compatible)
const yapl = new NodeYAPL({ baseDir: "./prompts" });

// Multiple base directories and remote alias support
// - You can pass an array for baseDir. Each entry is either
//   a local directory or the special alias "@awesome-yapl".
// - If the same relative path exists in multiple baseDirs, the LAST directory wins.
// - When using the alias, paths starting with "@awesome-yapl/" are fetched from
//   https://raw.githubusercontent.com/yapl-language/awesome-yapl/main/prompts
const yaplMulti = new NodeYAPL({
  baseDir: [
    "./company-prompts",     // private/local repository
    "./prompts",             // default local prompts
    "@awesome-yapl",         // public remote prompts (GitHub)
  ],
});

// You can now load local files or remote ones via the alias
await yaplMulti.render("tasks/summarize.md.yapl", { domain: "news" });
await yaplMulti.render("@awesome-yapl/agent/base.md.yapl", { name: "Neo" });

const result = await yapl.render("agent.md.yapl", {
  agent_name: "CodeBot",
  domain: "software development",
  user_level: "beginner",
});

console.log(result.content);

📚 Learn More: Check out the Quick Start Guide for a step-by-step tutorial, or explore Basic Examples to see more patterns.

🔧 API Reference

Node.js Usage

import { NodeYAPL } from "@yapl-language/yapl.ts/node";

const yapl = new NodeYAPL({
  // You can pass a string or an array for multiple base directories
  baseDir: ["./prompts", "@awesome-yapl"],
  strictPaths: true,
  maxDepth: 10,
  whitespace: {
    trimBlocks: true,
    lstripBlocks: true,
    dedentBlocks: true,
  },
});

// Render a template file
const result = await yapl.render("template.yapl", variables);

// Render a string directly
const result = await yapl.renderString(templateSource, variables);

Browser Usage

import { YAPL } from "@yapl-language/yapl.ts";

const yapl = new YAPL({
  baseDir: "/templates",
  loadFile: async (path) => {
    const response = await fetch(path);
    return response.text();
  },
  resolvePath: (templateRef, fromDir, ensureExt) => {
    return new URL(ensureExt(templateRef), fromDir).href;
  },
});

const result = await yapl.renderString(templateSource, variables);

Configuration Options

interface YAPLOptions {
  baseDir: string | string[]; // Base directory (or directories) for templates
  cache?: boolean; // Enable template caching (Node.js only)
  strictPaths?: boolean; // Strict path resolution (Node.js only)
  maxDepth?: number; // Maximum include/extend depth (default: 10)
  whitespace?: WhitespaceOptions; // Whitespace control options

  // Browser-specific options
  resolvePath?: (
    templateRef: string,
    fromDir: string,
    ensureExt: (p: string) => string
  ) => string;
  loadFile?: (absolutePath: string) => Promise<string>;
  ensureExtension?: (p: string) => string;
}

🎯 Language Concepts

📖 Deep Dive: For detailed explanations and advanced patterns, see the Template Inheritance, Mixins, Variables, and Conditionals guides.

Template Inheritance

{# base.yapl #}
{% block header %}
  Default Header
{% endblock %}
{% block content %}{% endblock %}

{# child.yapl #}
{% extends "base.yapl" %}
{% block content %}
  Child Content
{% endblock %}

Mixins for Composition

{# mixins/safety.yapl #}
{% block guidelines %}
  {{ super() }}
  - Never provide harmful information
{% endblock %}

{# agent.yapl #}
{% mixin "mixins/safety.yapl" %}

Dynamic Variables

Hello {{ name | default("there") }}!
{% if expertise %}
  You specialize in {{ expertise }}.
{% endif %}

Conditional Logic

{% if user_type == "developer" %}
  Technical documentation follows...
{% elif user_type == "designer" %}
  Design guidelines follow...
{% else %}
  General information follows...
{% endif %}

📚 Examples

🎯 More Examples: Explore AI Agent Templates and Complex Workflows for real-world use cases.

AI Agent Template

{# coding-assistant.yapl #}
{% extends "base/agent.yapl" %}
{% mixin "mixins/helpful.yapl", "mixins/technical.yapl" %}

{% block persona %}
  You are {{ name | default("CodeBot") }}, an expert programming assistant.
{% endblock %}

{% block capabilities %}
  {{ super() }}
  - Write and review code
  - Debug complex issues
  - Explain programming concepts
  - Suggest optimizations
{% endblock %}

{% block guidelines %}
  {{ super() }}
  {% if user_level == "beginner" %}
    - Use simple explanations
    - Provide step-by-step guidance
    - Include plenty of examples
  {% else %}
    - Use technical terminology
    - Focus on best practices
    - Provide concise expert advice
  {% endif %}
{% endblock %}

Multi-Context Prompt

{# contextual-assistant.yapl #}
# {{ title | default("AI Assistant") }}

{% if context == "customer_support" %}
  You are a patient, empathetic customer support agent.
  Focus on resolving issues and ensuring customer satisfaction.
{% elseif context == "tutoring" %}
  You are an encouraging tutor who breaks down complex concepts.
  Check for understanding and provide practice opportunities.
{% else %}
  You are a helpful general assistant.
{% endif %}

{% include "components/safety-guidelines.yapl" %}

🧪 Development

# Install dependencies
pnpm install

# Run tests with coverage
pnpm test

# Build the library
pnpm build

# Lint and format
pnpm run lint
pnpm run format

# Type checking
pnpm run typecheck

# Run all checks
pnpm run check

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: pnpm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• YAPL VS Code Extension - Syntax highlighting and language support
• YAPL Open VSX Extension - For VSCodium and Code OSS users
• YAPL Website - Interactive playground and documentation

🐛 Issues & Support

• GitHub Issues - Bug reports and feature requests
• Discord Community - Get help and discuss YAPL
• Documentation - Comprehensive guides and examples

Made with 💖 for the AI community by Einfach AI