# UWU-Template 🦄 A **blazingly fast, feature-rich template engine** for Deno and JavaScript with advanced component system, helper functions, template inheritance, and performance that rivals native template literals.

## ✨ Features - 🚀 **Ultra-fast performance** - 3-6x faster than popular alternatives - 🧩 **Advanced component system** - Reusable templates with props and parent data access - 🔧 **Enhanced helper functions** - Mixed string/variable arguments with type safety - 🏗️ **Template inheritance** - Extensible templates with block overrides - 📝 **Rich templating** - Variables, conditionals, loops, layouts, and raw blocks - 🛠️ **Enhanced error handling** - Detailed error messages with line numbers and context - 📦 **Lightweight** - Minimal dependencies, zero runtime overhead - ⚡ **Production-ready** - Battle-tested with comprehensive benchmarks - 🎯 **Type-safe** - Written in TypeScript with full type support - 📚 **Comprehensive documentation** - Complete guides and migration support ## 🆕 New in Latest Version - ✨ **Enhanced Error Reporting** - Get detailed error messages with line numbers and code context - 🧩 **Parent Data Access** - Components can access parent template data with `@parent` syntax - 🔧 **Mixed Helper Arguments** - Use both string literals and variables in helper functions - 📚 **Complete Documentation** - API reference, migration guides, and component examples - 🏗️ **Template Inheritance Foundation** - Extensible template system (foundation ready) - ⚡ **Improved Performance** - Better caching and error recovery ## 📖 Table of Contents - [Features](#-features) - [Quick Start](#-quick-start) - [Core Template Syntax](#-core-template-syntax) - [Helper Functions](#-helper-functions) - [Enhanced Component System](#-enhanced-component-system) - [Template Inheritance](#️-template-inheritance-preview) - [Performance Benchmarks](#-performance-benchmarks) - [Documentation](#-documentation) - [Migration from Other Engines](#-migration-from-other-engines) - [Contributing](#-contributing) ## 🚀 Quick Start ### Installation ```typescript // From CDN (recommended) import { compile, registerComponent, registerHelper, } from "https://cdn.jsdelivr.net/gh/Aiko-Suzuki/uwu-template@main/bundle.js"; // Or locally import { compile, registerComponent, registerHelper } from "./mod.ts"; ``` ### 🎨 VS Code Extension Get syntax highlighting, snippets, and IntelliSense for `.uwu` template files: **[📦 UWU-Template Language Support](https://marketplace.visualstudio.com/items?itemName=beingsuz.uwu-template-support)** Features: - 🌈 Syntax highlighting for `.uwu` files - 📝 Code snippets and auto-completion - 🔍 Template validation and error detection - 🎯 IntelliSense support ### Basic Usage ```typescript import { compile } from "./mod.ts"; // 1. Define your template const template = `

Welcome {{user.name}}!

{{#if user.premium}} Premium Member {{/if}}

{{name}} - ${{ price }}

`; // 2. Compile the template (with optional error context) const render = compile(template, { escape: true }, "userProfile"); const data = { title: "My Store", user: { name: "Alice", premium: true }, items: [ { name: "Widget A", price: 29.99 }, { name: "Widget B", price: 19.99 }, ], }; const html = render(data); console.log(html); ``` ### Error Handling UWU-Template now provides detailed error information to help you debug issues quickly: ```typescript import { compile, TemplateRuntimeError, TemplateSyntaxError } from "./mod.ts"; try { const render = compile(template, { escape: true }, "myTemplate"); const result = render(data); } catch (error) { if (error instanceof TemplateSyntaxError) { console.log(`Syntax error in template "${error.templateName}":`); console.log( `Line ${error.line}, Column ${error.column}: ${error.message}`, ); console.log(error.context); // Shows code context around the error } } ``` ## 📚 Core Template Syntax ### Variables ```handlebars {{title}} {{user.name}} {{items.0.price}} ``` ### Conditionals ```handlebars {{#if condition}} Content when true {{#elseif otherCondition}} Content when elseif is true {{#else}} Content when false {{/if}} {{#if user.isActive && user.premium}} Premium active user content {{/if}} ``` ### Loops ```handlebars {{#each items}}

{{name}} - ${{price}}

User {{@index}}: {{name}}

{{/each}} ``` ### Layouts ```typescript import { registerLayout } from "./mod.ts"; registerLayout( "main", ` {{title}} {{> header}}

{{> footer}} `, ); // Use in templates const template = ` {{> main}}

Page Content

`; ``` ### Raw Output For outputting literal template syntax without processing, use raw blocks: ```handlebars {{{{raw}}}}

{{{body}}}

This {{variable}} will not be processed

{{#if condition}}{{value}}{{/if}} {{{{/raw}}}} ``` **Output:** ```html

{{{body}}}

This {{variable}} will not be processed

{{#if condition}}{{value}}{{/if}} ``` **Use Cases:** - Generating template examples in documentation - Outputting template syntax for client-side processing - Creating code examples that contain template syntax - Bypassing template processing for specific content blocks ## 🔧 Helper Functions ### Built-in Helpers ```handlebars {{{json data}}} {{{raw content}}} ``` ### Custom Helpers with String Literals ```typescript import { registerHelper } from "./mod.ts"; // Register helpers with flexible argument types registerHelper("uppercase", (...args) => { const text = args[0]; return String(text).toUpperCase(); }); registerHelper("formatPrice", (...args) => { const price = args[0] as number; const currency = args[1] as string || "USD"; const prefix = args[2] as string || ""; return `${prefix}${currency} ${price.toFixed(2)}`; }); registerHelper("dateFormat", (...args) => { const date = args[0]; const format = args[1] as string || "short"; const d = new Date(date); return format === "long" ? d.toLocaleDateString() : d.toDateString(); }); ``` **Template Usage with Mixed Arguments:** ```handlebars {{{uppercase "hello world"}}} {{{formatPrice "29.99" "EUR"}}} {{{dateFormat "2025-01-01" "long"}}} {{{uppercase userName}}} {{{formatPrice product.price}}} {{{formatPrice productPrice "GBP" "Sale: "}}} {{{formatPrice price currency prefix}}} ``` ### Block Helpers ```typescript import { registerBlockHelper } from "./mod.ts"; registerBlockHelper("withUser", (user, options) => { if (user?.active) { return options.fn(user); } else { return options.inverse(); } }); ``` **Usage:** ```handlebars {{#withUser currentUser}}

Welcome {{name}}!

Please log in

{{/withUser}} ``` ## 🧩 Component System Components are reusable template fragments with their own props and access to parent data. ### Registering Components ```typescript import { registerComponent } from "./mod.ts"; // Simple component registerComponent("greeting", "Hello {{name}}!"); // Complex component with layout registerComponent( "userCard", `

{{#if @parent.showStatus}} {{#if active}}🟢 Online{{#else}}⚫ Offline{{/if}} {{/if}}

`, ); // Component composition registerComponent( "button", ``, ); registerComponent( "modal", ` `, ); ``` ### Using Components ```handlebars {{component "greeting" name="Alice"}} {{component "userCard" name="John Doe" email="john@example.com" avatar=user.profileImage active=user.isOnline}} {{component "modal" title="Confirm Action" message="Are you sure you want to continue?"}} ``` ### Parent Data Access Components can access parent template data using `@parent`: ```typescript registerComponent( "statusBadge", ` {{status}} ({{@parent.userCount}} users) `, ); ``` **Usage:** ```handlebars {{component "statusBadge" status="Online"}} ``` ### Enhanced Component System UWU-Template features a powerful component system that supports props, parent data access, and composition. ### Component Registration ```typescript import { registerComponent } from "./mod.ts"; registerComponent( "userCard", `

`, ); ``` ### Parent Data Access Components can access the parent template's data using the `@parent` syntax: ```typescript const data = { theme: "dark", users: [ { name: "Alice", email: "alice@example.com", role: "Admin" }, { name: "Bob", email: "bob@example.com", role: "User" }, ], }; ``` ```handlebars

{{#each users}} {{component "userCard" name=name email=email role=role avatar="/avatars/default.jpg"}} {{/each}}

``` ### Component Composition Build complex UIs by composing smaller components: ```typescript registerComponent( "button", ` `, ); registerComponent( "productCard", `

\${{price}}

{{component "button" text="Add to Cart" variant="primary" type="button"}} {{component "button" text="♡ Wishlist" variant="outline" type="button"}}

`, ); ``` ## 🎨 Real-World Examples ### E-commerce Product List ```typescript // Register components registerComponent( "productCard", `

{{{formatPrice price @parent.currency}}}

{{#if onSale}} On Sale! {{/if}} {{component "button" text="Add to Cart" variant="primary"}}

`, ); // Template const template = `

{{#each products}} {{component "productCard" name=name price=price image=image onSale=onSale}} {{/each}}

`; // Data const data = { currency: "USD", products: [ { name: "iPhone 15", price: 999, image: "/iphone15.jpg", onSale: false, }, { name: "MacBook Pro", price: 2499, image: "/macbook.jpg", onSale: true, }, ], }; ``` ### Blog with Layout System ```typescript registerLayout( "blogLayout", ` {{title}} - {{@parent.siteName}} {{> header}}

{{> footer}} `, ); registerComponent( "articleCard", `

By {{author}} {{{dateFormat publishedAt "long"}}}

`, ); const template = ` {{> blogLayout}}

{{#each posts}} {{component "articleCard" title=title slug=slug author=author publishedAt=publishedAt excerpt=excerpt}} {{/each}}

`; ``` ## 🏗️ Template Inheritance (Preview) UWU-Template includes a foundation for template inheritance, allowing you to extend base templates: ```typescript import { registerBaseTemplate } from "./mod.ts"; // Register a base template registerBaseTemplate( "basePage", ` {{#block "title"}}Default Title{{/block}}

{{#block "header"}}Default Header{{/block}}

{{#block "content"}}Default Content{{/block}}

`, ); ``` ```handlebars {{extends "basePage"}} {{#block "title"}}My Custom Page{{/block}} {{#block "content"}}

Welcome!

This content overrides the base template.

{{/block}} ``` _Note: Template inheritance is currently in development. The foundation is complete and ready for full implementation._ ## 📊 Performance Benchmarks **🚀 Performance Summary:** - **1.7x faster** than Pug - **4-7x faster** than Handlebars, EJS, and Mustache - **Identical performance** to native Template Literals - **Fastest** template engine in most scenarios - **Enhanced caching** for better performance with error handling - **Sub-millisecond** compilation times for complex templates ### Detailed Results | Template Engine | Simple Templates | Complex Templates | Large Templates | | ----------------- | ---------------- | ----------------- | --------------- | | **UWU-Template** | **374.2 ns** | **24.9 µs** | **300.1 µs** | | Template Literals | 362.3 ns | 24.9 µs | 396.0 µs | | Pug | 536.9 ns | 41.5 µs | 518.2 µs | | Mustache | 2.3 µs | 106.8 µs | 1.2 ms | | Handlebars | 5.1 µs | 111.9 µs | 1.2 ms | | EJS | 2.9 µs | 170.5 µs | 1.7 ms | ### Real-World Performance - **E-commerce templates**: 48,913 renders/sec (0.020ms per render) - **Blog post templates**: 128,739 renders/sec (0.008ms per render) - **Email templates**: 365,141 renders/sec (0.003ms per render) 📊 **[View complete benchmark results](./BENCHMARK_RESULTS.md)** ### Run Benchmarks Yourself ```bash deno task bench ``` 📈 **[View detailed benchmark results](./BENCHMARK_RESULTS.md)** ## 🛠️ Advanced Usage ### File-based Templates ```js // Read template from file const template = await Deno.readTextFile("./templates/layout.html"); const render = compile(template); const result = render({ title: "My Website", content: "Hello, world!", }); ``` ## ⚡ Performance Benchmarks UWU-Template consistently outperforms popular template engines: ``` Template Engine Performance (renders/second): ┌─────────────────┬──────────────────┬────────────────┐ │ Engine │ Simple Templates │ Complex Templates │ ├─────────────────┼──────────────────┼────────────────┤ │ UWU-Template │ 283,763/s │ 38,939/s │ │ Handlebars │ 85,000/s │ 12,000/s │ │ EJS │ 72,000/s │ 15,000/s │ │ Mustache │ 95,000/s │ 18,000/s │ │ Template Literals│ 290,000/s │ 45,000/s │ └─────────────────┴──────────────────┴────────────────┘ UWU-Template is 3-6x faster than alternatives! ``` ### Why So Fast? - **Compilation-based**: Templates are compiled to optimized JavaScript functions - **Zero runtime dependencies**: No parsing overhead during rendering - **Smart caching**: Compiled templates are cached for reuse - **Minimal overhead**: Direct property access with optional chaining - **Optimized code generation**: Hand-tuned JavaScript output ### Benchmark Details ```typescript // Run benchmarks yourself deno task bench // Or manually deno run --allow-read bench/performance.bench.ts ``` ## 📖 Complete API Reference ### Core Functions #### `compile(template, options?)` Compiles a template string into a render function. ```typescript interface CompilerOptions { escape?: boolean; // Default: true } const render = compile(templateString, { escape: false }); const html = render(data); ``` #### `registerHelper(name, function)` Registers a custom helper function. ```typescript registerHelper("helperName", (...args: unknown[]) => { // Helper logic return "result"; }); ``` #### `registerBlockHelper(name, function)` Registers a block helper with `fn` and `inverse` support. ```typescript registerBlockHelper( "blockName", (context: unknown, options: BlockHelperOptions) => { if (condition) { return options.fn(context); } else { return options.inverse(context); } }, ); ``` #### `registerComponent(name, template)` Registers a reusable component. ```typescript registerComponent( "componentName", `

{{prop1}} - {{@parent.parentData}}

`, ); ``` #### `registerLayout(name, template)` Registers a layout template. ```typescript registerLayout( "layoutName", ` {{content}} `, ); ``` ### Template Syntax Reference #### Variables ```handlebars {{variable}} {{object.property}} {{array.0.property}} {{#if variable}}{{/if}} ``` #### Conditionals ```handlebars {{#if condition}} True content {{#else}} False content {{/if}} {{#if condition1}} First {{#elseif condition2}} Second {{#else}} Default {{/if}} {{#if user.isActive && user.premium}} Premium user content {{/if}} ``` #### Loops ```handlebars {{#each items}}

Item {{@index}}: {{name}}

{{/each}} {{/each}} ``` #### Helpers ```handlebars {{{helperName "string literal"}}} {{{helperName "string" "another"}}} {{{helperName variable}}} {{{helperName variable1 variable2}}} {{{helperName variable "string" anotherVariable}}} ``` #### Components ```handlebars {{component "componentName"}} {{component "componentName" prop1="value" prop2=variable}}

{{prop}} - {{@parent.parentVariable}}

``` #### Layouts ```handlebars {{> layoutName}} {{> layoutName}}

This content goes into the layout

``` #### Raw Output ```handlebars {{{{raw}}}}

{{{body}}}

This {{variable}} will not be processed

{{#if condition}}{{value}}{{/if}} {{{{/raw}}}} ``` ### Error Handling UWU-Template gracefully handles missing data: ```typescript const template = `{{user.name}} - {{user.missing.property}}`; const render = compile(template); const result = render({ user: { name: "Alice" } }); // Output: "Alice - " (missing properties render as empty) ``` ### TypeScript Support Full TypeScript support with proper typing: ```typescript import { compile, registerComponent, registerHelper } from "./mod.ts"; // Type-safe helper registration registerHelper("typedHelper", (value: string, format: string) => { return `${format}: ${value}`; }); // Type-safe data passing interface User { name: string; email: string; } const render = compile(`Hello {{name}}!`); const result = render({ name: "Alice" } as User); ``` ### Production Tips #### Pre-compilation ```typescript // Compile templates at startup, not per request const templates = { userProfile: compile(userProfileTemplate), dashboard: compile(dashboardTemplate), email: compile(emailTemplate), }; // Fast rendering per request app.get("/profile", (req, res) => { const html = templates.userProfile(req.user); res.send(html); }); ``` #### Component Libraries ```typescript // Create reusable component libraries export function registerUIComponents() { registerComponent("button", buttonTemplate); registerComponent("card", cardTemplate); registerComponent("modal", modalTemplate); // ... more components } // Use across your application registerUIComponents(); ``` #### Performance Optimization ```typescript // Use unescaped output for trusted content const template = `{{{trustedHtmlContent}}}`; // Minimize helper calls in loops {{#each largeArray}} {{{precomputedValue}}} {{/each}} // Cache component instances const cachedComponents = new Map(); ``` ## 🔧 Advanced Features ### Custom Block Helpers ```typescript registerBlockHelper("repeat", (count: number, options) => { let result = ""; for (let i = 0; i < count; i++) { result += options.fn({ index: i, value: i + 1 }); } return result; }); ``` ```handlebars {{#repeat 3}}

Item {{value}} (index {{index}})

{{/repeat}} ``` ### Helper with Hash Options ```typescript registerHelper("link", (text: string, options) => { const url = options.hash?.url || "#"; const target = options.hash?.target || "_self"; return `${text}`; }); ``` ```handlebars {{{link "Click here" url="https://example.com" target="_blank"}}} ``` ### Complex Component Composition ```typescript registerComponent( "dataTable", ` {{#each @parent.columns}} {{/each}} {{#each rows}} {{component "tableRow" rowData=this columns=@parent.columns}} {{/each}}

{{title}}

`, ); registerComponent( "tableRow", ` {{#each columns}} {{lookup ../rowData field}} {{/each}} `, ); ``` ## 🧪 Testing UWU-Template includes comprehensive tests: ```bash # Run all tests deno test --allow-read # Run specific test files deno test --allow-read production.test.ts deno test --allow-read real-world.test.ts # Run benchmarks deno run --allow-read bench/performance.bench.ts ``` ## 🔧 Available Features | Feature | Status | Example | | ------------------------- | ------ | -------------------------------------- | | Variables | ✅ | `{{name}}` | | Nested Properties | ✅ | `{{user.email}}` | | Conditionals | ✅ | `{{#if active}}...{{/if}}` | | Else/ElseIf | ✅ | `{{#else}}...{{/else}}` | | Complex Conditions | ✅ | `{{#if a && b}}...{{/if}}` | | Loops | ✅ | `{{#each items}}...{{/each}}` | | Layouts | ✅ | `{{> layoutName}}` | | Helpers (String Literals) | ✅ | `{{{helper "string"}}}` | | Helpers (Variables) | ✅ | `{{{helper variable}}}` | | Helpers (Mixed) | ✅ | `{{{helper var "str"}}}` | | Block Helpers | ✅ | `{{#blockHelper}}...{{/blockHelper}}` | | Components | ✅ | `{{component "name" prop="value"}}` | | Parent Data Access | ✅ | `{{@parent.data}}` | | Component Composition | ✅ | Components using components | | HTML Escaping | ✅ | Automatic (use `{{{...}}}` to disable) | | TypeScript Support | ✅ | Full type safety | | Performance Optimization | ✅ | Compilation-based rendering | ## 🚀 Migration from Other Engines UWU-Template provides clear migration paths from popular template engines. See our **[complete migration guide](./docs/MIGRATION_GUIDE.md)** for detailed examples. ### From Handlebars (4.5x Performance Improvement) UWU-Template is largely compatible with Handlebars syntax: ```handlebars {{variable}} {{#if condition}}...{{/if}} {{#each items}}...{{/each}} {{component "name" prop="value"}} {{{helper "string literal"}}} {{@parent.data}} ``` **Migration effort**: ⭐ **Minimal** - Most templates work without changes ### From EJS (6.8x Performance Improvement) ```javascript // EJS <%- include('partial', {data: value}) %> <% if (user.active) { %>Active<% } %> // UWU-Template {{component "partial" data=value}} {{#if user.active}}Active{{/if}} ``` **Migration effort**: ⭐⭐⭐ **Moderate** - Syntax changes but clear patterns ### From Mustache (4.3x Performance Improvement) ```handlebars {{#items}}{{name}}{{/items}} {{#each items}}{{name}}{{/each}} {{component "itemCard" name=name}} ``` **Migration effort**: ⭐⭐ **Easy** - Similar syntax with more capabilities ### From Pug (1.7x Performance + 2655x Faster Compilation) ```pug // Pug doctype html html head title= title body each item in items li= item.name // UWU-Template {{title}} {{#each items}}

{{/each}} ``` **Migration effort**: ⭐⭐⭐⭐ **Significant** - Complete restructure but major performance gains ### Migration Support Tools - **[Migration Guide](./docs/MIGRATION_GUIDE.md)** - Step-by-step conversion guides - **Performance Comparisons** - Before/after benchmarks - **Syntax Converters** - Patterns for common conversions - **Best Practices** - Optimization tips for each engine ## 📚 Documentation UWU-Template now includes comprehensive documentation to help you get started quickly: ### 📖 Complete Guides - **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation with examples - **[Migration Guide](./docs/MIGRATION_GUIDE.md)** - Migrate from Handlebars, EJS, Mustache, Pug - **[Component Examples](./docs/COMPONENT_EXAMPLES.md)** - Real-world component patterns - **[Performance Benchmarks](./BENCHMARK_RESULTS.md)** - Detailed performance analysis ### 🚀 Quick References - **Template Syntax** - Variables, conditionals, loops, and more - **Component System** - Props, composition, and parent data access - **Helper Functions** - Custom functions with mixed argument types - **Error Handling** - Debugging with detailed error messages - **Performance Tips** - Optimization strategies and best practices ### 🔧 Development Resources - **TypeScript Support** - Full type definitions included - **Error Recovery** - Graceful handling of template issues - **Debugging Tools** - Line numbers and code context in errors - **Migration Helpers** - Tools to convert from other engines ## 🤝 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. **Run tests**: `deno test -A` 4. **Run benchmarks**: `deno task bench` 5. **Add your changes with tests** 6. **Update documentation** if needed 7. **Commit**: `git commit -m 'Add amazing feature'` 8. **Push**: `git push origin feature/amazing-feature` 9. **Open a Pull Request** ### Development Setup ```bash # Clone the repo git clone https://github.com/your-username/uwu-template.git cd uwu-template # Run tests (all should pass) deno test -A # Run enhanced features demo deno run -A enhanced-demo.ts # Run benchmarks deno task bench # Check formatting deno fmt --check # Check linting deno lint # Build bundle deno task build ``` ### Documentation - All public APIs are documented in `docs/API_REFERENCE.md` - Component examples are in `docs/COMPONENT_EXAMPLES.md` - Migration guides are in `docs/MIGRATION_GUIDE.md` - Update documentation when adding features ### Testing - Add tests for new features in appropriate test files - Ensure backward compatibility - Test error handling scenarios - Benchmark performance impact for major changes ## 🌟 Sponsor This project is proudly sponsored by [yatsu.net](https://yatsu.net) ## 📄 License MIT License - see the [LICENSE](LICENSE) file for details. ## � Changelog See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes and version history. ## �🙏 Acknowledgments - Inspired by Handlebars, Mustache, and EJS - Built for the Deno community - Performance benchmarks against industry standards - Enhanced with comprehensive documentation and developer experience improvements --- ## 🎯 What's Next? - 🏗️ **Complete Template Inheritance** - Full block override system - 🔧 **Advanced Helper Features** - More built-in helpers and utilities - 🚀 **Streaming Templates** - Support for large dataset streaming - 📱 **Framework Integrations** - Plugins for popular frameworks - 🎨 **Template Designer** - Visual template builder **🦄 Made with care for modern web development** _UWU-Template: Because your templates deserve to be fast AND adorable!_ 📊 **Performance** • 🧩 **Components** • 🔧 **Helpers** • 📚 **Documentation** • 🚀 **Migration**