> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder.md).

# Template Builder for developers

[Template Builder](https://docs.scaleflex.com/studio/template-builder.md) is the design tool in Scaleflex Studio. An author builds a template once, marks the parts that change as variables, and every image after that comes from the same template.

These pages are about the two programmatic surfaces around it:

* **The render URL.** A saved template is a file in the DAM, and requesting its URL with a query string renders an image. No SDK is involved. See [The render URL](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md).
* **The widget.** `@scaleflex/template-builder` embeds the editor itself in your own application, so your users build and edit templates without leaving it. See [Getting started](https://docs.scaleflex.com/developers-headless/studio/template-builder/getting-started.md).

The two are independent. Plenty of integrations only ever need the render URL.

### Which surface you need

| If you want to                                             | Use                                                                                                                               |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Generate images from templates someone else authored       | [The render URL](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md)                            |
| Let your own users edit templates in your application      | The widget, in [DAM-backed mode](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md)         |
| Let your users edit templates that your application stores | The widget, in [stateless mode](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md)          |
| Fill variables from your own product data                  | [Custom metadata](https://docs.scaleflex.com/developers-headless/studio/template-builder/custom-metadata.md), plus the render URL |
| Talk to the editor without the widget                      | [The postMessage protocol](https://docs.scaleflex.com/developers-headless/studio/template-builder/postmessage-protocol.md)        |

### What the widget is

`<sfx-template-builder>` is a custom element. It loads the editor from a Template Builder deployment in an iframe, hands over the credential, and re-publishes everything the editor does as ordinary DOM `CustomEvent`s. From your side it behaves like any other component.

It is a protocol adapter, not a renderer. Server-side text rendering, font resolution, asset browsing and the template document all stay inside the deployment. That has one consequence worth knowing up front: **an embedded editor always needs an authenticated Scaleflex tenant**, even when your own application owns the template document. [How rendering works](https://docs.scaleflex.com/developers-headless/studio/template-builder/how-rendering-works.md) explains why.

### Two choices to make

Embedding means picking a storage mode and a credential. They are related: one combination is not available.

|                         | DAM-backed                      | Stateless |
| ----------------------- | ------------------------------- | --------- |
| Who stores the template | Scaleflex, as a file in the DAM | You do    |
| Hub session             | Yes                             | Yes       |
| Security template       | No                              | Yes       |

A **security template** is a permission-scoped guest credential you define once in your Scaleflex project. It needs no Scaleflex identity for any of your users, which is what makes it the usual choice for an external integration - and it works in stateless mode only.

[Storage modes](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) and [Authentication](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) each go into one of these in full.

### Before you start

You need:

* A Scaleflex account with Studio enabled on the project, and a running Template Builder deployment to point `base-url` at.
* A credential minted on your server. Never hardcode one in a public bundle.
* Your page's origin added to the deployment's embedding allowlist. See [Embedding and origins](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md) - this one is easy to miss and produces a blank frame rather than an error message.
* A browser with Custom Elements v1. The floors are in [Embedding and origins](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md), and they are higher than a plain web component would need, because cross-site embedding depends on partitioned cookies.

### Where to go next

* [Getting started](https://docs.scaleflex.com/developers-headless/studio/template-builder/getting-started.md) - install it and get an editor on screen
* [The render URL](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md) - render images without embedding anything
* [API reference](https://docs.scaleflex.com/developers-headless/studio/template-builder/api-reference.md) - every attribute, method and event
