@withstudiocms/template-lang

v0.1.0 GitHub npm Changelog

StudioCMS comes with its own custom template language that is similar in syntax to popular templating languages like Handlebars^ or Liquid^. This template language allows you to create dynamic and reusable templates in different parts of the StudioCMS dashboard, such as in the Mail Templates system, or in custom plugins that you may develop.

@withstudiocms/template-lang is a simple MIT Licensed TypeScript ESM template language for HTML emails, similar to Handlebars but focused on simplicity and database data integration.

Features

Simple {{variable}} syntax for variable interpolation
Support for nested properties with dot notation ({{user.name}})
TypeScript with full ESM support
Strict mode for error handling
Designed specifically for email templates and DB data
Zero dependencies

Use Cases

Perfect for:

HTML email templates
Dynamic content generation from database data
Simple templating needs without complex logic
ESM-first TypeScript projects

Installation

For those interested in using the StudioCMS template language in their projects, you can install using your preferred package manager:

npm i @withstudiocms/template-lang

pnpm add @withstudiocms/template-lang

yarn add @withstudiocms/template-lang

Template Syntax

Similar to other templating languages, StudioCMS’s template language uses double curly braces {{ }} to denote variables that should be replaced with actual data when the template is rendered.

Unlike some other templating languages, StudioCMS’s template language focuses on simplicity and does not include complex logic or control structures. It is primarily designed for straightforward variable interpolation.

Variable Interpolation

<h1>Hello {{user.firstName}} {{user.lastName}}!</h1>
<p>Your order #{{order.id}} total is ${{order.total}}</p>

Nested Properties

<p>Shipping to: {{user.address.street}}, {{user.address.city}}</p>

Usage Examples

Basic Usage

import TemplateEngine from '@withstudiocms/template-lang';
const engine = new TemplateEngine();

const template = "Hello {{name}}! Welcome to {{company.name}}.";
const data = {
    name: "John Doe",
    company: {
        name: "Acme Corp"
    }
};

const result = engine.render(template, data);
console.log(result); // "Hello John Doe! Welcome to Acme Corp."

Email Template

import TemplateEngine from '@withstudiocms/template-lang';
const engine = new TemplateEngine();

const emailTemplate = `
<!DOCTYPE html>
<html>
<head>
    <title>{{subject}}</title>
</head>
<body>
    <h1>Hello {{user.name}}!</h1>
    <p>Your order #{{order.id}} has been confirmed.</p>
    <p>Total: {{order.total}}</p>
</body>
</html>
`;

const data = {
    subject: "Order Confirmation",
    user: { name: "John Doe" },
    order: { id: "12345", total: "99.99" }
};

const html = engine.render(emailTemplate, data);

Strict Mode

import TemplateEngine from '@withstudiocms/template-lang';

const strictEngine = new TemplateEngine({ strict: true });

// This will throw an error if 'missingVar' is not in data
try {
    const result = strictEngine.render("Hello {{missingVar}}!", {});
} catch (error) {
    console.log("Variable not found:", (error as Error).message);
}

Default Values

import TemplateEngine from '@withstudiocms/template-lang';

const engine = new TemplateEngine({ defaultValue: "[NOT SET]" });
const result = engine.render("Hello {{name}}!", {});
// Result: "Hello [NOT SET]!"

Template Compilation

import TemplateEngine from '@withstudiocms/template-lang';
const engine = new TemplateEngine();

// Compile once, use multiple times
const compiled = engine.compile("Hello {{name}}!");

const result1 = compiled({ name: "Alice" });
const result2 = compiled({ name: "Bob" });

API Reference

TemplateEngine

Constructor

new TemplateEngine(options?: TemplateOptions)

Methods

render(template: string, data: TemplateData): string Renders a template with the provided data.

compile(template: string): (data: TemplateData) => string Compiles a template into a reusable function.

hasVariables(template: string): boolean Checks if a template contains any variables.

getVariables(template: string): string[] Returns an array of all variable names in the template.

setOptions(options: Partial<TemplateOptions>): void Updates the engine options.

Options

interface TemplateOptions {
    strict?: boolean;      // Throw error on missing variables (default: false)
    defaultValue?: string; // Default value for missing variables (default: '')
}