​
Introduction

While Compozy provides several built-in libraries (like Lodash and Day.js) for template expressions, you can extend this functionality by adding your own dependencies. These dependencies should focus on synchronous data manipulation and transformation operations.

Since Compozy uses Deno runtime, dependencies should be compatible with Deno’s module system. Additionally, template expressions are meant for data transformation, not for async operations.

​
Limitations

Keep in mind the following limitations when using custom dependencies:

  • Dependencies must be compatible with Deno’s module system
  • Only synchronous operations are supported in templates
  • Async operations (HTTP, file I/O) are not allowed
  • Some npm packages might not work in Deno context

​
Adding Dependencies

Custom dependencies are specified in your document’s frontmatter using the template-dependencies field. All custom dependencies are automatically namespaced under the $ object to avoid naming conflicts:

---
name: "My Document"
template-dependencies:
  - package: "npm:mathjs@11.8.0"
    name: math
  - package: "jsr:@mikemcl/decimal.js@10.4.3"
    name: decimal
---

All custom dependencies are accessible through the $ object in your templates. For example:

  • $.math for Math.js functions
  • $.decimal for Decimal.js operations

This namespacing prevents conflicts with built-in variables and functions while keeping your custom dependencies organized.

​
Usage Examples

result: "{{ $.math.evaluate('2x + 3y', { x: 4, y: 2 }) }}"
# Output: 14

matrix:
  $exec: |
    const result = $.math.inv([[1, 2], [3, 4]]);
    return result;
# Output: [[-2, 1], [1.5, -0.5]]

​
Best Practices

1

Version Management

Always specify exact versions in the package URL:

template-dependencies:
  - package: "npm:mathjs@11.8.0"
    name: math
  - package: "jsr:@mikemcl/decimal.js@10.4.3"
    name: decimal
2

Deno Compatibility

  • Use libraries that are compatible with Deno’s module system
  • Avoid libraries that rely on Node.js specific features
  • Check the library’s ESM compatibility
3

Performance

  • Import only necessary packages
  • Use lightweight alternatives when possible
  • Consider bundle size impact
4

Error Handling

Implement proper error handling in your template expressions:

result:
  $exec: |
    try {
      return $.math.evaluate('invalid expression');
    } catch (error) {
      return { error: error.message };
    }

​
Dependency Documentation

When using custom dependencies, refer to their official documentation for available methods and usage:

​
Common Use Cases

Mathematical Operations

Use Math.js for complex calculations, matrix operations, and unit conversions

Precise Calculations

Handle financial calculations with Decimal.js for exact decimal arithmetic

​
Built-in Libraries

Compozy includes several popular libraries by default:

  • Lodash (_) - Utility functions for arrays, objects, and more
  • Day.js (dayjs) - Modern date/time manipulation
  • Voca (v) - String manipulation and formatting
  • Numeral.js (numeral) - Number formatting

See Template Functions for details on built-in libraries.

​
Next Steps

Template Expressions

Learn about the template expression system

Flow Control

Explore flow control in templates

Examples

See real-world template examples

Built-in Functions

Review built-in template functions