@terralang/terra

Terra.js Beta

Terra is a powerful yet lightweight template engine for Node.js, Bun, Deno and more that supports async operations, middleware, error boundaries, and nested components - all powered by the Tereact Engine at the core.

Table of Contents

• Installation
• Quick Start
• Core Concepts
• Configuration
• Template Syntax
• Components
• Middleware
• Helpers
• Error Handling
• API Reference

Installation

npm install @terralang/terra

Quick Start

import Terra from '@terralang/terra';

// Initialize Terra with configuration
const terra = new Terra({
  root: './views',
  cache: true,
  debug: true
});

// Render a template
const html = await terra.render('index.trx', {
  title: 'My Page',
  user: { name: 'John' }
});

Core Concepts

Terra.js is built around several key concepts:

1. Templates: Text files containing dynamic content using Terra's syntax
2. Components: Reusable template pieces that can be nested and composed
3. Middleware: Functions that process data before rendering
4. Helpers: Utility functions available in templates
5. Error Boundaries: Graceful error handling during rendering

Configuration

Terra accepts the following configuration options:

const terra = new Terra({
  cache: boolean,          // Enable template caching (default: true in production)
  debug: boolean,          // Enable debug logging (default: true in development)
  errorBoundary: boolean,  // Enable error boundaries (default: true)
  middleware: Array,       // Array of middleware functions
  helpers: Object,         // Object of helper functions
  root: string            // Root directory for templates
});

Template Syntax

Expressions

• Basic expression: <%= value %>
• Async expression: <%= await asyncFunction() %>

Conditionals

<% if (condition) { %>
  Content when true
<% } else { %>
  Content when false
<% } %>

Loops

<% for (let item of items) { %>
  <%= item %>
<% } %>

Components

Components are reusable template pieces that can be imported and nested.

Defining Components

<!-- Header.trx -->
<header>
  <h1><%= title %></h1>
  <%= children %>
</header>

Importing and Using Components

<!-- index.trx -->
import Header from './Header.trx'

<Header title="My Page">
  <nav>Navigation content</nav>
</Header>

Props

Components accept props as attributes:

<UserCard name="John" age={25} data={userData} />

Middleware

Middleware functions process data before rendering:

terra.use(async (context) => {
  // Modify or enhance context
  context.timestamp = Date.now();
  return context;
});

Helpers

Helpers are utility functions available in templates:

terra.addHelper('formatDate', (date) => {
  return new Date(date).toLocaleDateString();
});

// In template:
<%= helpers.formatDate(date) %>

Error Handling

Terra provides built-in error handling through error boundaries:

// Enable error boundaries in config
const terra = new Terra({
  errorBoundary: true
});

// Errors will be caught and displayed in development
<%= potentially.invalid.expression %>

API Reference

Terra Class

Constructor

new Terra(options: TerraOptions)

Methods

render(path: string, data?: object): Promise<string>

Renders a template at the given path with optional data.

use(middleware: Function): Terra

Adds a middleware function to the stack.

addHelper(name: string, fn: Function): Terra

Adds a helper function for use in templates.

loadComponent(componentPath: string, parentPath?: string): Promise<string>

Loads a component from the filesystem.

Error Types

Terra throws TerraError with the following types:

• INVALID_MIDDLEWARE: Invalid middleware function
• INVALID_HELPER: Invalid helper function
• COMPONENT_NOT_FOUND: Component file not found
• EXPRESSION_ERROR: Error in template expression

Best Practices

1. Component Organization

   • Keep components in a dedicated directory
   • Use meaningful component names
   • Split large components into smaller ones

2. Performance

   • Enable caching in production
   • Use async expressions judiciously
   • Minimize complex logic in templates

3. Error Handling

   • Enable error boundaries in development
   • Use try-catch blocks in middleware
   • Provide fallback content for critical components

4. Security

   • Sanitize user input
   • Avoid using raw HTML unless necessary
   • Validate component props

Environment Variables

Terra respects the following environment variables:

• NODE_ENV: Controls default cache and debug settings
  • production: Enables caching, disables debug
  • development: Disables caching, enables debug