Playt

A powerful and flexible prompt templating library for AI applications

Playt is a modern templating system specifically designed for AI prompts. It combines the simplicity of Markdown with the power of Nunjucks templating, offering variable interpolation, validation, conditionals, loops, and more.

✨ Features

• 📝 Markdown-first: Write templates in familiar Markdown format
• 🎯 Type-safe: Full TypeScript support with type validation
• 🔍 Validation: Built-in variable validation with custom rules
• 🎨 Flexible: Use as a library or CLI tool
• ⚡ Progressive: Start simple, add features as needed
• 🧩 Powerful templating: Conditionals, loops, filters, and more via Nunjucks
• 🚀 Zero config: Works out of the box with sensible defaults

📦 Installation

npm install playt

For CLI usage, install globally:

npm install -g playt

🚀 Quick Start

As a Library

import { render, validate } from 'playt';

// Simple template
const template = `
---
variables:
  name:
    type: string
    required: true
---

Hello {{ name }}!
`;

// Validate variables
const validation = validate(template, { name: 'World' });
if (!validation.valid) {
  console.error(validation.errors);
}

// Render template
const result = render(template, { name: 'World' });
console.log(result); // "Hello World!"

As a CLI

# Create a new template
playt init greeting.md

# Render with variables
playt render greeting.md -v name="World"

# Validate template
playt validate greeting.md -v name="Test"

# Inspect template structure
playt inspect greeting.md

📖 Template Format

Templates use YAML frontmatter for configuration and Nunjucks for content:

---
description: A greeting template
variables:
  name:
    type: string
    required: true
    description: Name to greet
  greeting:
    type: string
    default: Hello
    description: Greeting to use
---

{{ greeting }} {{ name }}!

{% if name == "World" %}
Welcome to everyone!
{% endif %}

🎯 Core Concepts

Variables

Define variables with type checking and validation:

variables:
  email:
    type: string
    required: true
    validation:
      pattern: "^[^@]+@[^@]+\\.[^@]+$"
  age:
    type: number
    validation:
      min: 18
      max: 120
  items:
    type: array
    required: true

Templating

Use Nunjucks syntax for dynamic content:

{# Conditionals #}
{% if user.premium %}
Premium content here
{% endif %}

{# Loops #}
{% for item in items %}
- {{ item.name }}: {{ item.price }}
{% endfor %}

{# Filters #}
{{ text | upper }}
{{ items | length }}

🛠️ API Reference

render(template, variables)

Renders a template with the provided variables.

import { render } from 'playt';

const result = render(template, { name: 'World' });

validate(template, variables)

Validates variables against template requirements.

import { validate } from 'playt';

const result = validate(template, { name: 'World' });
if (!result.valid) {
  console.error(result.errors);
}

💻 CLI Commands

• playt render <template> - Render a template
• playt validate <template> - Validate a template and variables
• playt inspect <template> - Show template information
• playt init <name> - Create a new template

Run playt --help for detailed command information.

📚 Documentation

For comprehensive documentation, visit our documentation site:

• Installation Guide
• Library Usage
• CLI Usage
• API Reference
• Examples

🎓 Examples

Check out the examples directory for practical use cases:

• Simple templates
• Variable usage
• Validation
• Conditionals
• JSON output
• And more...

🔧 Development

Setup

npm install

Build

npm run build

Test

npm test

Documentation

Serve documentation locally:

npm run docs:serve

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

MIT

🙏 Acknowledgments

Playt is built with:

• Nunjucks - Powerful templating engine
• gray-matter - YAML frontmatter parser
• Commander - CLI framework