Templates

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.

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.

Description

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.

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.

Build Process

Templates must be built before publishing. The build process compiles the Next.js page, bundles dependencies, optimizes assets, and uploads the result to a CDN.

The build executes five steps:

1. Dependency installation - Installs NPM packages from package.json
2. Next.js compilation - Builds the page with production optimizations
3. Asset optimization - Compresses images, minifies JavaScript and CSS
4. CDN upload - Uploads build artifacts to the content delivery network
5. Metadata update - Records the CDN URL and build status

Build failures typically result from missing dependencies, TypeScript errors, or invalid Next.js configuration. Check build logs for specific error messages.

Customization

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

Customization fields support five data types:

color

Hex color values for branding and theming. Rendered as a color picker in the installation UI.

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

number

Numeric values for intervals, limits, and quantities. Supports integers and decimals.

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

boolean

Feature flags and toggles. Rendered as a checkbox in the installation UI.

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

string

Text values for names, URLs, and configuration strings.

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

select

Enumerated options from a predefined list. Rendered as a dropdown menu.

{
  "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.

Examples

Creating a Template

This example creates a cryptocurrency portfolio tracker template with customization options.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "mirra-templates",
    "templatePath": "crypto-dashboard",
    "gitHash": "main",
    "name": "Crypto Dashboard",
    "description": "Real-time cryptocurrency portfolio tracker",
    "version": "1.0.0",
    "category": "crypto",
    "tags": ["crypto", "dashboard", "portfolio"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "template_abc123",
    "name": "Crypto Dashboard",
    "status": "draft",
    "createdAt": "2025-11-15T12:00:00Z"
  }
}

Building a Template

Build the template to prepare it for publishing.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0"
  }'

Response

{
  "success": true,
  "data": {
    "buildStatus": "success",
    "buildOutput": "Built successfully",
    "cdnUrl": "https://cdn.getmirra.app/templates/crypto-dashboard-v1",
    "logs": [
      "Installing dependencies...",
      "Building Next.js app...",
      "Uploading to CDN...",
      "Build completed"
    ]
  }
}

Checking Installation Requirements

Verify whether a user can install a template and view estimated costs.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/check-requirements \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "canInstall": true,
    "missingResources": [],
    "estimatedCost": {
      "setup": 0,
      "monthly": 5.0,
      "perUse": 0.01
    },
    "requirements": {
      "scripts": ["fetchPrices", "calculatePortfolio"],
      "resources": ["crypto-price-api"]
    }
  }
}

The missingResources array lists required resources the user has not yet installed. Installation fails if required resources are missing.

Installing a Template

Install a template with custom configuration values.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/install \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customization": {
      "branding.primaryColor": "#FF6B6B",
      "api.refreshInterval": 30,
      "features.notifications": true
    }
  }'

Response

{
  "success": true,
  "data": {
    "installationId": "inst_123",
    "templateId": "template_456",
    "pageUrl": "https://crypto-dashboard.user.getmirra.app",
    "installedScripts": ["fetchPrices", "calculatePortfolio"],
    "installedResources": ["crypto-price-api"],
    "customization": {
      "branding.primaryColor": "#FF6B6B",
      "api.refreshInterval": 30,
      "features.notifications": true
    }
  }
}

The installation process validates dependencies, deploys scripts, installs resources, builds the page, assigns a subdomain, and applies customization.

Publishing a Template

Publish a template to the marketplace with pricing configuration.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing": {
      "setupFee": 10.0,
      "monthlyFee": 5.0,
      "estimatedUsageCost": {
        "perUse": 0.01,
        "perMonth": 10.0
      }
    }
  }'

Publishing Requirements

• Template successfully built with valid CDN URL
• All resource dependencies available in marketplace
• Complete metadata (name, description, version)

To unpublish and remove from marketplace:

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/unpublish \
  -H "Authorization: Bearer YOUR_API_KEY"

Pricing

Templates use composite pricing that combines setup fees, recurring hosting costs, and usage-based charges.

{
  "pricing": {
    "setupFee": 10.0,
    "monthlyFee": 5.0,
    "estimatedUsageCost": {
      "perUse": 0.01,
      "perMonth": 10.0,
      "breakdown": {
        "scripts": 7.0,
        "resources": 3.0
      }
    }
  }
}

Pricing Components:

• setupFee - One-time installation fee charged when the template is first installed
• monthlyFee - Recurring monthly hosting fee for page deployment and subdomain
• estimatedUsageCost.perUse - Estimated cost per script execution or resource call
• estimatedUsageCost.perMonth - Estimated total monthly usage cost based on typical usage
• breakdown - Cost breakdown showing script execution and resource API costs separately

Actual usage costs vary based on script invocation frequency and resource pricing. The platform tracks usage and bills users monthly.

Versioning

Templates use semantic versioning (MAJOR.MINOR.PATCH) to track changes and enable safe updates.

Version Format

• 1.0.0 - Major.Minor.Patch for stable releases
• 1.0.0-beta.1 - Pre-release versions with label and number
• 1.0.0-alpha.3 - Alpha versions for early testing

Creating Versions

curl -X POST https://api.fxn.world/api/sdk/v1/templates/TEMPLATE_ID/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.1.0",
    "gitHash": "def456",
    "changelog": "Added notification support"
  }'

Each version references a specific Git commit hash, enabling reproducible builds and rollback capabilities. Users can upgrade installations to newer versions or pin to specific versions.

Troubleshooting

Build Failures

When template builds fail, check the build logs for specific error messages. Common causes include:

• Missing dependencies in package.json - Verify all imports have corresponding package entries
• TypeScript compilation errors - Run tsc --noEmit locally to identify type issues
• Invalid Next.js configuration - Ensure next.config.js follows Next.js 13+ App Router conventions
• CDN upload failures - Verify network connectivity and CDN credentials

To debug locally, clone the repository and run npm run build to reproduce build errors.

Installation Failures

Installation fails when dependencies are missing or incompatible. Common issues:

• Missing required resources - Check check-requirements endpoint before installation
• Incompatible versions - Verify template version compatibility with platform version
• Insufficient permissions - Ensure API key has templates:install permission
• Quota exceeded - Check account limits for templates, scripts, and resources

Install missing resources manually before attempting template installation.

Customization Not Applied

When customization values do not appear in the deployed template:

• Verify field keys in customization request match template.json definitions exactly
• Confirm data types match field type specifications (string, number, boolean, color, select)
• Check that values are within allowed ranges or option sets
• Rebuild the template after changing customization configuration

Customization values are injected at build time, not runtime. Changes require a rebuild.

See Also

• Scripts - Serverless functions for template backend logic
• Resources - API integrations for template functionality
• Examples: Templates - Complete template implementation examples
• Example Template Repository - Reference implementation
• Marketplace - Browse published templates