Templates Overview

Templates are installable application bundles that combine Next.js pages, serverless scripts, and API resources into a single deployable package. Templates enable developers to distribute complete, customizable solutions on the marketplace with automatic subdomain deployment and dependency management.

What are Templates?

Templates provide a distribution mechanism for complete applications on the Mirra marketplace. Each template bundles a Next.js frontend, serverless backend scripts, and external API integrations into a single installable package that users can deploy with customization.

When a user installs a template, the platform performs several operations: validates dependencies, deploys scripts to the Mirra platform, builds and uploads the Next.js page to a CDN, assigns a unique subdomain, and applies user customization. The result is a fully functional application accessible at template-name.username.getmirra.app.

Syntax

Creating a Template

POST /api/sdk/v1/templates

Template Structure

{
  "name": "Template Name",
  "description": "Template description",
  "repository": "repository-name",
  "templatePath": "path/to/template",
  "gitHash": "branch-or-commit",
  "version": "1.0.0",
  "includes": {
    "page": { /* Page configuration */ },
    "scripts": [ /* Script definitions */ ],
    "resources": [ /* Resource references */ ]
  },
  "customization": { /* Customization fields */ }
}

Template Components

Templates consist of three primary components that work together to create complete applications.

Page

page

A Next.js page component that serves as the template's user interface. Pages are built, optimized, and deployed to a CDN with automatic subdomain assignment.

{
  "includes": {
    "page": {
      "type": "nextjs",
      "entryPoint": "page.tsx",
      "buildOutput": "https://cdn.getmirra.app/templates/example-template"
    }
  }
}

Pages support React Server Components, client-side interactivity, and the full Next.js App Router feature set.

Scripts

scripts

Serverless functions that provide backend logic, data processing, and API integrations. Scripts are deployed to the Mirra platform and can be invoked by the page or triggered by events.

{
  "includes": {
    "scripts": [
      {
        "name": "fetchPrices",
        "code": "export async function handler(event) {...}",
        "description": "Fetches cryptocurrency prices"
      },
      {
        "name": "calculatePortfolio",
        "code": "export async function handler(event) {...}",
        "description": "Calculates portfolio value"
      }
    ]
  }
}

Scripts can invoke Resources and subscribe to Events.

Resources

resources

References to marketplace resources that the template depends on. Resources can be required (installation fails without them) or optional (enhanced functionality when available).

{
  "includes": {
    "resources": [
      {
        "id": "crypto-price-api",
        "required": true,
        "description": "Required for price data"
      },
      {
        "id": "notification-service",
        "required": false,
        "description": "Optional price alerts"
      }
    ]
  }
}

During installation, the platform automatically installs required resources and prompts for optional ones.

Repository Structure

Templates are stored in Git repositories with a standardized directory structure:

mirra-templates/
├── crypto-dashboard/
│   ├── page.tsx              # Main page component
│   ├── components/           # Reusable components
│   ├── scripts/             # Script definitions
│   │   └── fetchPrices.ts
│   ├── template.json         # Template metadata
│   └── README.md

The template.json file defines the template configuration, including name, version, dependencies, and customization options. The page.tsx file serves as the Next.js page entry point.

See a complete working example at github.com/Oz-Networks/mirra-sdk/tree/main/templates/example-template

When to Use Templates

Templates are ideal for:

Complete Applications - Distribute full-stack applications with frontend and backend
Marketplace Distribution - Publish and monetize complete solutions
Customizable Solutions - Allow users to personalize branding and features
Multi-Component Systems - Bundle pages, scripts, and resources together
Subdomain Deployment - Provide users with dedicated URLs for their installations

Templates abstract away deployment complexity, allowing users to install and customize applications without managing infrastructure.

Customization

Templates support user customization through configurable fields. Customization enables users to personalize branding, behavior, and feature flags without modifying code.

Customization Field Types

Color

{
  "key": "branding.primaryColor",
  "label": "Primary Color",
  "type": "color",
  "default": "#3B82F6",
  "description": "Main brand color"
}

Number

{
  "key": "api.refreshInterval",
  "label": "Refresh Interval (seconds)",
  "type": "number",
  "default": 60,
  "description": "How often to fetch new data"
}

Boolean

{
  "key": "features.notifications",
  "label": "Enable Notifications",
  "type": "boolean",
  "default": false,
  "optional": true
}

String

{
  "key": "app.title",
  "label": "Application Title",
  "type": "string",
  "default": "My App"
}

Select

{
  "key": "theme.mode",
  "label": "Theme Mode",
  "type": "select",
  "options": ["light", "dark", "auto"],
  "default": "auto"
}

Customization values are injected into the template at installation time and accessible in both page components and scripts through environment variables.

Next Steps

Endpoints - Complete API reference for all template operations
Examples - Practical template implementations
Technical Notes - Build process, versioning, and troubleshooting