Template Technical Notes

This page covers advanced topics for template development including the build process, customization system, versioning, and troubleshooting common issues.

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.

Build Steps

The build executes five steps:

Dependency installation - Installs NPM packages from package.json
Next.js compilation - Builds the page with production optimizations
Asset optimization - Compresses images, minifies JavaScript and CSS
CDN upload - Uploads build artifacts to the content delivery network
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.

Build Configuration

Configure the build process in template.json:

{
  "build": {
    "buildCommand": "npm run build",
    "outputDirectory": ".next",
    "environmentVariables": {
      "NODE_ENV": "production"
    }
  }
}

Customization System

Templates support user customization through configurable fields that are injected at installation time.

Field Types

Color Fields

{
  "key": "branding.primaryColor",
  "type": "color",
  "default": "#3B82F6",
  "validation": {
    "pattern": "^#[0-9A-Fa-f]{6}$"
  }
}

Number Fields

{
  "key": "api.refreshInterval",
  "type": "number",
  "default": 60,
  "min": 30,
  "max": 300,
  "step": 10
}

Boolean Fields

{
  "key": "features.enableNotifications",
  "type": "boolean",
  "default": false
}

String Fields

{
  "key": "app.title",
  "type": "string",
  "default": "My App",
  "maxLength": 100
}

Select Fields

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

Accessing Customization Values

In Page Components:

// Values are injected as environment variables
const primaryColor = process.env.NEXT_PUBLIC_BRANDING_PRIMARY_COLOR;
const refreshInterval = Number(process.env.NEXT_PUBLIC_API_REFRESH_INTERVAL);

In Scripts:

export async function handler(event, context) {
  // Values are available in context.customization
  const color = context.customization['branding.primaryColor'];
  const interval = context.customization['api.refreshInterval'];
}

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.

Pricing Models

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

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

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.

Best Practices

Security

Never hardcode API keys or secrets in template code
Use environment variables for all sensitive configuration
Validate all user inputs in scripts
Implement proper authentication for page endpoints
Follow Next.js security best practices

Performance

Optimize images and assets before bundling
Use Next.js Image component for automatic optimization
Implement proper caching strategies
Minimize JavaScript bundle size
Use server components where possible

Maintenance

Keep dependencies up to date
Test template installations regularly
Monitor user feedback and bug reports
Document breaking changes in changelogs
Support at least two previous major versions