Templatical

English

Deutsch

English

Deutsch

Appearance

Getting Started ​

This guide walks you through setting up Templatical Cloud in your application.

Prerequisites ​

  • A Templatical Cloud account with an active plan
  • A project and tenant configured in the Cloud dashboard
  • The @templatical/editor package installed in your project

Installation ​

If you haven't already installed the editor, add it along with the cloud dependencies:

bash
npm install @templatical/editor @templatical/media-library pusher-js

@templatical/media-library provides the built-in media browser and pusher-js enables real-time collaboration. Both are optional peer dependencies — only needed when using initCloud().

Shadow DOM

initCloud() inherits all shadow-DOM behavior from the editor — mounted inside a Shadow DOM by default for host-CSS isolation. The media browser, AI panels, comments, and snapshot UI all teleport into the editor's shadow-aware popover root, so no special handling is needed. Pass shadowDom: false to opt out. See the Shadow DOM guide.

Authentication Endpoint ​

Cloud features require an authentication endpoint on your server that issues access tokens. The SDK calls this endpoint automatically to obtain and refresh tokens.

Laravel Example ​

php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

Route::post('/api/templatical/token', function (Request $request) {
    $response = Http::post('https://templatical.com/api/v1/auth/token', [
        'client_id' => config('templatical.client_id'),
        'client_secret' => config('templatical.client_secret'),
        'tenant' => $request->user()->tenant_id,
    ]);

    return $response->json();
});

Node.js Example ​

js
app.post('/api/templatical/token', async (req, res) => {
  const response = await fetch('https://templatical.com/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.TEMPLATICAL_CLIENT_ID,
      client_secret: process.env.TEMPLATICAL_CLIENT_SECRET,
      tenant: req.user.tenantId,
    }),
  });

  res.json(await response.json());
});

Initialize the Cloud Editor ​

Replace init() with initCloud() and provide your auth endpoint:

js
import { initCloud } from '@templatical/editor';

const editor = await initCloud({
  container: '#editor',
  auth: {
    url: '/api/templatical/token',
    requestOptions: {
      method: 'POST',
      credentials: 'same-origin',
    },
  },
});

The auth.url should point to the token endpoint you created above. The SDK handles token refresh automatically.

Configuration Options ​

initCloud() accepts all the same options as init() (theme, locale, merge tags, custom blocks, etc.) plus Cloud-specific options:

js
const editor = await initCloud({
  container: '#editor',
  auth: {
    url: '/api/templatical/token',
  },

  // Cloud features (all optional)
  ai: {},                       // Enable all AI features
  collaboration: {             // Enable real-time collaboration
    enabled: true,
  },
  commenting: true,            // Enable inline comments
  savedBlocks: true,           // Saved blocks (default; false to disable)

  // Callbacks
  onChange: (content) => { /* template changed */ },
  onSave: (result) => { /* SaveResult: { templateId, html, mjml, content } */ },
  onError: (error) => { /* handle errors */ },
  onComment: (event) => { /* comment created/updated/deleted */ },
});

Working with Templates ​

Create a New Template ​

js
const template = await editor.create();
// template.id is now available for saving, sharing, etc.

Load an Existing Template ​

js
const template = await editor.load('template-id-here');

Save Changes ​

js
const result = await editor.save();

Export ​

The Cloud editor does not expose a client-side toMjml() method. The Templatical Cloud backend converts saved template JSON to MJML server-side, with additional processing the browser can't do alone (e.g., signed image URLs, asset rewriting). Trigger an export through the backend HTTP API after saving — see the headless API docs for endpoints.

If you want client-side MJML rendering instead (no backend round-trip), use the OSS editor (init, not initCloud) along with @templatical/renderer.

Cleanup ​

When the user navigates away, unmount the editor to clean up WebSocket connections and event listeners:

js
editor.unmount();

Health Check ​

Verify your Cloud connection is working:

js
import { performHealthCheck } from '@templatical/core/cloud';

const result = await performHealthCheck({
  baseUrl: 'https://templatical.com',
});

console.log(result.overall);    // true if all services are reachable
console.log(result.api);        // { ok: true, latency: 42 }
console.log(result.websocket);  // { ok: true }
console.log(result.auth);       // { ok: true }

Next Steps ​