#Unofficial Unlayer Alpine.js SDK

Alpine.js adapter for @community-sdks/unlayer-ts.

#Development

Build the package:

npm run build

Serve the local examples:

npm run examples:serve

Then open one of these pages in the browser:

http://127.0.0.1:4174/examples/basic.html
http://127.0.0.1:4174/examples/http-template-client.html

Do not open the example files with file://. Browser module imports from the local filesystem are blocked and the examples are designed to run over HTTP.

#Getting Started

npm install @community-sdks/unlayer-alpinejs @community-sdks/unlayer-ts alpinejs

#Register With Alpine

import Alpine from 'alpinejs'
import { registerUnlayerAlpine } from '@community-sdks/unlayer-alpinejs'

registerUnlayerAlpine(Alpine)

Alpine.start()

You can also choose a custom component name:

registerUnlayerAlpine(Alpine, 'unlayerEditor')

#Examples

examples/basic.html registers the Alpine adapter, mounts the editor with a sample design, and exports the current state.

examples/http-template-client.html shows how to combine the Alpine adapter with HttpTemplateClient and backend template proxy routes.

#Usage

<div
    x-data="unlayerEditor({
        id: 'editor',
        displayMode: 'email',
        uploadImage: async file => {
            const data = new FormData()
            data.append('file', file)

            const response = await fetch('/your-upload-endpoint', {
                method: 'POST',
                body: data,
            })

            const body = await response.json()

            return body.url
        },
        onChange: state => {
            console.log(state.html, state.design)
        },
    })"
>
    <div id="editor" style="height: 700px"></div>

    <button type="button" x-on:click="exportState()">Export</button>
    <button type="button" x-on:click="openTemplates()">Choose template</button>
</div>

#Alpine API

The component exposes the core SDK through Alpine-friendly properties and methods:

ready
mounted
loading
error
state
templates
templatesOpen
templatesLoading
templateSearch

mount()
isReady()
getState()
setState(state)
loadDesign(design)
exportState()
searchTemplates(options)
refreshTemplates()
loadTemplate(slug)
chooseTemplate(templateOrSlug)
openTemplates()
closeTemplates()
setTemplateSearch(search)

When templatePicker.enabled is on, openTemplates() and closeTemplates() delegate to the built-in picker UI from @community-sdks/unlayer-ts.

#Stock Templates

Template search and loading comes from the underlying TypeScript SDK. Unlayer's public stock template search endpoint does not allow browser CORS requests, so browser apps need a backend proxy endpoint.

Register a template client that calls your own backend:

import Alpine from 'alpinejs'
import { registerUnlayerAlpine } from '@community-sdks/unlayer-alpinejs'
import { HttpTemplateClient } from '@community-sdks/unlayer-ts'

window.templateClient = new HttpTemplateClient({
    searchUrl: '/templates',
    loadUrl: '/templates/:slug',
})

registerUnlayerAlpine(Alpine)
Alpine.start()

Then pass that client and default filters:

<div
    x-data="unlayerEditor({
        id: 'editor',
        templateClient: window.templateClient,
        templateSearch: {
            search: 'newsletter',
            type: 'email',
            premium: false,
            limit: 20,
            offset: 0,
            collection: '',
            sort: 'recent',
        },
    })"
>
    <div id="editor" style="height: 700px"></div>
</div>

Your backend should expose:

GET /templates
GET /templates/{slug}

Relative URLs call the same domain as the page. For example, /templates becomes https://your-app.test/templates.

If your template backend is on another domain, use full URLs:

window.templateClient = new HttpTemplateClient({
    searchUrl: 'https://api.example.com/templates',
    loadUrl: 'https://api.example.com/templates/:slug',
})

When using full URLs on another domain, that backend must allow CORS for your frontend domain.

The browser calls your backend, and your backend calls Unlayer. Using Axios instead of fetch does not bypass CORS because the browser enforces it before JavaScript can read the response.

#Upstream Unlayer Template API

Your backend proxy should call Unlayer's search endpoint:

POST https://unlayer.com/templates/search
Content-Type: application/json

Search options map to Unlayer's JSON body:

search     -> filter.name
type       -> filter.type
premium    -> filter.premium, "true" when true, "" when false
limit      -> perPage
offset     -> page, calculated as floor(offset / limit) + 1
collection -> filter.collection
sort       -> filter.sortBy

Example body:

{
    "page": 1,
    "perPage": 20,
    "filter": {
        "premium": "",
        "collection": "",
        "name": "newsletter",
        "sortBy": "recent",
        "type": "email"
    }
}

Template thumbnails use https://api.unlayer.com/v2/stock-templates/{slug}/thumbnail?width=500.

Template designs are loaded through:

POST https://studio.unlayer.com/api/v1/graphql

Using StockTemplate(slug: $slug) { StockTemplatePages { design } }.

#Uploads

Uploads are intentionally application-owned. Provide uploadImage(file) and return the public URL:

uploadImage: async file => {
    return 'https://example.com/path/to/uploaded-image.png'
}

This package does not depend on Filament, Livewire, Vue, or React.