PromptX

A flexible and extensible Prompt DSL for building AI prompts with templates, variables, chaining, and intelligent expansion.

📚 Documentation

📖 Full Documentation - Complete guides, API reference, and examples

🚀 Features

• 🔧 Prompt Builder: Chain-based API for building complex prompts
• 📝 Template System: Structured templates with semantic blocks
• 🔄 Variable Substitution: Dynamic content with {{variable}} syntax
• 🌳 Branching Logic: Conditional content with SWITCH statements
• ⚡ Conditional Logic: IF/THEN/ELSE statements for dynamic prompts
• 🛠️ Tool Integration: Built-in support for function calling and tool requirements
• 📚 Content Organization: Hierarchical content with important, critical, and example sections
• 🎯 Role Management: System, user, and assistant role definitions
• 🔨 Direct Utility Functions: Use when(), block(), importants() etc. directly for custom prompts
• 🔄 Flexible Architecture: Combine builder pattern with direct functions for maximum control
• ⚙️ TypeScript Support: Full type safety and IntelliSense
• 🧪 100% Test Coverage: Comprehensive testing suite
• 🚀 Zero Dependencies: Pure TypeScript with no external runtime dependencies
• 📦 Ultra Lightweight: Minimal bundle size for optimal performance

📦 Installation

# Using pnpm (recommended)
pnpm add @promptsx/core

# Using npm
npm install @promptsx/core

# Using yarn
yarn add @promptsx/core

💡 Zero Dependencies: PromptX has no external runtime dependencies, ensuring your bundle stays lean and your deployments remain fast.

🎯 Quick Start

import { P, PromptNode } from '@promptsx/core'

const builder = P()
const systemNode = new PromptNode('system')

systemNode
  .setRole('code-assistant', 'A helpful coding assistant')
  .content('You are an expert developer')
  .important('Always provide working code examples')

builder.nodes.push(systemNode)
const prompt = builder.build()

console.log(prompt)

📖 Learn More

• 🚀 Getting Started - Quick start guide and core concepts
• 📚 API Reference - Complete API documentation
• 💡 Examples - Practical examples and use cases
• ✅ Best Practices - Guidelines for effective usage

🏗️ Project Structure

promptx/
├── src/                      # Source code (Zero Dependencies)
│   ├── builder.ts            # Main prompt builder
│   ├── node.ts               # Prompt node implementation
│   ├── branch.ts             # Branching logic
│   ├── common.ts             # Utility functions
│   ├── tool.ts               # Tool integration
│   ├── index.ts              # Main exports
│   └── *.test.ts             # Test files
├── docs/                     # Documentation (VitePress)
├── dist/                     # Built files
├── build.config.ts           # Build configuration
├── vitest.config.ts          # Test configuration
├── tsconfig.json             # TypeScript configuration
└── package.json              # No runtime dependencies

💡 Architecture: Pure TypeScript code with zero external runtime dependencies, ensuring maximum compatibility and minimal bundle size.

🔧 Development

Prerequisites

• Node.js 18+
• pnpm 8+

Setup

# Clone repository
git clone https://github.com/murongg/promptx.git
cd promptx

# Install dependencies
pnpm install

# Build packages
pnpm build

# Run tests
pnpm test

# Start documentation
pnpm docs:dev

Scripts

Script	Description
pnpm build	Build all packages
pnpm dev	Development mode with watch
pnpm test	Run tests
pnpm lint	Run ESLint
pnpm typecheck	TypeScript type checking
pnpm docs:dev	Start documentation server
pnpm docs:build	Build documentation

🚀 Performance & Size

PromptX is designed for maximum efficiency and minimal footprint:

• 🚀 Zero Dependencies: Pure TypeScript with no external runtime dependencies
• 📦 Ultra Lightweight: Minimal bundle size (< 5KB gzipped)
• ⚡ High Performance: Optimized string operations and memory management
• 🔄 Scalable: Handles large amounts of content efficiently
• 💾 Memory Efficient: No unnecessary object creation or memory leaks
• 🌐 Tree-shakable: Only import what you need, reduce bundle size further

🔒 Type Safety

Full TypeScript support with comprehensive type definitions:

// All methods are fully typed
const builder: PromptBuilder = P()
const node: PromptNode = new PromptNode('system')
const branch: BranchBuilder = node.branch('type')

// Type-safe variable access
node.var('name', 'value') // ✅
node.var(123, 'value') // ❌ Type error

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📞 Support

• Issues: GitHub Issues
• Author: MuRong [email protected]
• Documentation: https://promptx.dev

🙏 Acknowledgments

• Built with modern TypeScript and ES modules
• Zero external runtime dependencies for maximum compatibility
• Comprehensive testing with Vitest
• ESLint configuration by Anthony Fu
• Built with Unbuild for optimal bundling
• Designed for minimal bundle size and maximum performance

---

Built with ❤️ by MuRong