> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Dependencies
> Learn how to add and use custom JavaScript libraries in your template expressions for data manipulation and transformation.
## 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:
```yaml theme={"dark"}
---
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
```yaml Math Operations theme={"dark"}
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]]
```
```yaml Decimal Arithmetic theme={"dark"}
price:
$exec: |
const cost = new $.decimal('123.456789');
return cost.toDecimalPlaces(2).toString();
# Output: "123.46"
```
## Best Practices
Always specify exact versions in the package URL:
```yaml theme={"dark"}
template-dependencies:
- package: "npm:mathjs@11.8.0"
name: math
- package: "jsr:@mikemcl/decimal.js@10.4.3"
name: decimal
```
* 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
* Import only necessary packages
* Use lightweight alternatives when possible
* Consider bundle size impact
Implement proper error handling in your template expressions:
```yaml theme={"dark"}
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:
* [Math.js Documentation](https://mathjs.org/docs/index.html)
* [Decimal.js Documentation](https://mikemcl.github.io/decimal.js/)
## Common Use Cases
Use Math.js for complex calculations, matrix operations, and unit conversions
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](/core/template-engine/template-functions) for details on built-in libraries.
## Next Steps
Learn about the template expression system
Explore flow control in templates
See real-world template examples
Review built-in template functions