# Template Tiger Integration Guide

> **Integration pattern: Store templates locally, upload via /templates/upload, call POST /api/v1/templates/{name}/render from backend.**

This guide helps developers integrate Template Tiger into their application codebases.

## Recommended Approach: Server-Side Rendering

1. **Store templates locally** as `.html` or `.hbs` files in your project. This ensures your templates are version-controlled alongside your code.
2. **Upload templates** to Template Tiger via the web UI at `/templates/upload`.
   - Filenames become template names (extensions removed).
   - Example: `welcome-email.html` becomes template name `welcome-email`.
3. **Call the render API** from your backend when you need rendered HTML.
4. **Use the rendered HTML** for emails, PDFs, or dynamic content.

## Template Naming Convention

Template names can only contain letters, numbers, hyphens, and underscores. Slashes and dots are not supported.

When integrating, use a consistent naming convention:

```
# Local file                    # Template name in Template Tiger
emails/welcome.html         ->  welcome-email
emails/password-reset.hbs   ->  password-reset
invoices/monthly.html       ->  monthly-invoice
```

> **Note on File Upload:** When uploading templates via `/templates/upload`, the filename (without extension) is used as the template name. Ensure your filenames are valid according to the naming convention above. If you have nested directories locally, you should flatten them or use hyphens in filenames before uploading.

## Recommended Code Pattern

```javascript
// templateService.js
const TEMPLATE_TIGER_URL = "https://app.templatetiger.dev";
const API_KEY = process.env.TEMPLATE_TIGER_API_KEY;

async function renderTemplate(templateName, variables) {
  const response = await fetch(
    `${TEMPLATE_TIGER_URL}/api/v1/templates/${templateName}/render`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
      },
      body: JSON.stringify(variables)
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Template render failed: ${error.error.message}`);
  }

  return response.text();
}

// Usage
const welcomeHtml = await renderTemplate("welcome-email", {
  user: { firstName: "Amina", lastName: "Khan" },
  ctaUrl: "https://example.com/activate"
});
```

## Web Interface Reference

- **Templates List**: `/templates`
- **Create Template**: `/templates/create`
- **Upload Templates**: `/templates/upload`
- **View Template**: `/templates/{name}/view`
- **Configure Test Data**: `/templates/{name}/configure-test`
- **API Keys**: `/api-keys`
- **Swagger UI**: `/swagger-ui/index.html`