Installation

Install the Blocks package:

npm install [email protected]

Add the Blocks build plugin to your bundled app configuration (it copies package assets into the output and injects UseblocksEnvironment.publicPath for chunk URLs). Without the helper plugin you must set the bundle base URL yourself.

Agents & automation checklist

Use this when generating integration code or reviewing PRs against the Blocks plugin SDK. Canonical typings live in useblocks.d.ts (ExportedApi); avoid inventing field names.

For how merged ExportedApi interfaces, AppEvent, and payload types fit together (and how handleSubjectChanged differs), see docs/plugin-types-agents.md in the upstream authoring repository.

| Rule | Details | | --- | --- | | init | content is mandatory. init(options) → Promise<Instance>. | | Module vs instance | The useblocks bundle exports init (plus optional named ESM APIs). setConfig, show, save, destroy belong to the init return value—not the namespace object. | | Same DOM repeat | Calling init again on an existing mount triggers reset. Avoid parallel init on one container. | | Events | instance.handle*(…) usually returns unsubscribe. handleSubjectChanged / handlePreheaderChanged use bespoke signatures — see typings. | | Async | Handlers plus getAuthToken may be async; funnel errors via handleError or your own telemetry. | | Build | Without Webpack/Vite helpers you must wire UseblocksEnvironment / publicPath. Expect a heavy UI bundle (React, Monaco, etc.). | | Auth | Prefer getAuthToken or jwtAuth; keep client_secret on the server only. | | File manager | Wire storageProvider + config.imageCenterFileManagerView and read the StorageProvider contract before stubbing backends. | | commonStyles | Optional on init / reset: content-styles object (partial merge with COMMON_STYLES). Details — docs/plugin-content-styles.md in the authoring repository. |

Reference HTML samples (plugin_default.html, etc.) live under src/pluginExamples/ in the authoring repository.

Webpack

Use the exported class constructor with matching variable name:

const UseblocksWebpackPlugin = require('useblocks/webpack');

module.exports = {
  plugins: [
    new UseblocksWebpackPlugin({
      // Optional: outputFolder, modulesPath, publicPath — see package.
    }),
  ],
};

Vite

The factory returns an array of two plugins (serve + build) — spread it into plugins:

import { defineConfig } from 'vite';
import useblocksVite from 'useblocks/vite';

export default defineConfig({
  plugins: [
    ...useblocksVite({
      // Optional: outputFolder, modulesPath, publicPath — see package.
    }),
  ],
});

Initialization

Import the plugin in application code:

import * as useblocks from 'useblocks';

init requires content (HTML string or email/template wrapper). Methods such as setConfig, updateConfig, show, save are on the instance returned from init, not on the useblocks namespace object.

Typical root fields include getAuthToken or jwtAuth, element, content, config, project, baseUrl, storageProvider, commonStyles.

• commonStyles — optional content-styles preset merged with shipped COMMON_STYLES (see docs/plugin-content-styles.md in the authoring repository). Partial objects are safe.

• getAuthToken — (user?, project?, prevToken?) => string | Promise<string>. Obtain client_secret only from your backend; never expose it in the browser.

• jwtAuth — alternative to getAuthToken: { email, password, remember? } (see useblocks.d.ts or shipped typings).

ESM builds also expose named exports (for example useblocks-esm.js):

import { init, parseAMP, COMMON_STYLES, version, helpers, errors } from 'useblocks';

parseAMP parses AMP email code without UI; COMMON_STYLES is the default content-styles object for this build (spread into init({ commonStyles })); documented in src/constants/commonStyles.defaults.ts. version is the build string; helpers / errors include HTTP helpers and error classes (e.g. file manager).

Fetching the OAuth token on the backend

curl --location 'https://api.useblocks.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=*******' \
--data-urlencode 'client_secret=*******' \
--data-urlencode 'grant_type=client_credentials'

Creating the plugin instance

useblocks
  .init({
    getAuthToken,
    element: '#test',
    content: {
      subject: 'Email subject',
      html: 'EMAIL_CODE',
    },
    config: {},
  })
  .then((instance) => {});

You can take EMAIL_CODE from our sample or paste your own HTML.

For debugging, the dev build may support a front-end token flow — configure an auth proxy in your app if you use that path.

Configuration

Configuration is a nested object: editor chrome, initial email payload, and callback hooks.

Calling init again on the same DOM host internally performs reset with the new options — avoid two concurrent init calls on one container.

Element

Pass a selector string, an Element, or a DocumentFragment. Omitting element can run in background mode without a visible host.

Content

Possible shapes:

{string}

Raw HTML markup for the email.

{object} email fields

{
  id?: string; // Unique email ID in your system.
  html?: string;
  subject?: string;
  preheader?: string;
}

{object} Template, blocks, comments

{
  templateId?: string | number; // Template ID inside Blocks.
  email?: object;
  blocks?: [],
  comments?: [],
}

After init, update with instance.show(content).

Content styles (commonStyles)

Top-level init / reset option (not inside config). Shallow docs here — full reference: docs/plugin-content-styles.md.

• COMMON_STYLES named export — default preset for this product build.
• Partial overrides are deep-merged with COMMON_STYLES so UI panels stay consistent.
• Saved email.common_styles wins over init.commonStyles when present.
• Clear stored plugin override with commonStyles: undefined on reset / updateConfig.
• Show the sidebar tab via config.commonStylesEnabled (usually default true).

Config

Editor UI tuning. Use instance.setConfig, instance.updateConfig, instance.getConfig after init — not useblocks.setConfig / useblocks.updateConfig.

Parameter list (config)

| Parameter | Description | Default | | ---------------------- | --------------------------------- | ------- | | theme | Plugin theme: light, dark. | light | | autosaveTimeout | Delay before autosave, ms. | 10000 | | mergeTags | JSON with the list of dynamic variables. | undefined | | styles | String with styles in CSS format. | '' | | | | | | headerShow | Show header. | true | | headerArrowBackVisible | Show “Back” arrow. | true | | headerTitleVisible | Show “Subject” field. | true | | headerPreheaderVisible | Show “Preheader” field. | true | | historyEnabled | Show “Version history” button. | true | | codeEnabled | Show “Code mode” button. | true | | codeModeDirection | Default code editor display mode | none|left|right|bottom| | codeSideEnabled | Show “Code mode” button when desktop/mobile toggle is available. | true | | previewIconEnabled | Show “Preview” button. | true | | previewModeEnabled | Link to Preview. | true | | livePreviewEnabled | Show “Email client testing” button. | true | | sendTestEnabled | Show “Send test” button. | true | | sharePreviewEnabled | Show “Share” button. | true | | webversionEnabled | Show link to web version. | true | | commonStylesEnabled | Show content styles. | true | | emailResponsiveControlEnabled | Show email responsiveness toggle. | true | | templateNotEmAlertShow | Show alert that template is not from EM. | true | | | | | | emailDropdownMenuEnabled | Show email menu. | true | | emailDropdownMenuClone | Show “Clone” item. | true | | emailDropdownMenuImport | Show “Import” item. | true | | emailDropdownMenuImportButton | Show “Import” as a button. | true | | emailDropdownMenuLock | Show “Lock” item. | true | | emailDropdownMenuRemove | Show “Delete” item. | true | | | | | | emailExportEnabled | Show “Export” button. | true | | exportHtmlEnabled | Export to HTML. | true | | exportZipEnabled | Export to ZIP. | true | | exportClipboardEnabled | Export to clipboard. | true | | exportWebHookEnabled | Export to webhook. | true | | exportOutlookEnabled | Export to Outlook. | true | | exportPdfEnabled | Export to PDF. | true | | exportPngEnabled | Export to PNG. | true | | | | | | nextButtonEnabled | Show secondary button. | false | | nextButtonText | Text on secondary button. | '' | | saveButtonEnabled | Show primary button. | true | | saveButtonText | Text on primary button. | '' | | commandButtonsEnabled | Show primary and secondary buttons. | true | | | | | | sidePanelFloating | Floating side panel. | true | | desktopMobileSwitchRule | Modes switch bar. | true | | desktopMobileSwitchPanel | Modes switch panel. | false | | onlyCodeModeInMobile | Show only code on mobile. | false | | | | | | pathEnabled | Show breadcrumbs. | true | | copyPasteEnabled | Show copy–paste block in iframe. | true | | saveBlockEnabled | Show save block button. | true | | editImageControlEnabled | Show image editing button. | true | | | | | | menuDirection | Side panel position. | 'right' | | defaultBuildPanel | Default opened tab setting. | ''/'empty'/'project'/'common'/'template' | | commentsEnabled | Show “Comments” button. | true | | aiAssistentEnabled | Show “AI assistant”. | true | | optimizeEnabled | Show “Optimization” button. | true | | optimizeLinksEnabled | Show links check. | true | | optimizeImagesEnabled | Show images check. | true | | optimizeSpamAssassinEnabled | Show SpamAssassin check. | true | | optimizeCheckCodeEnabled | Show code check. | true | | settingsEnabled | Show “Settings” button. | true | | UTMEnabled | Show UTM tags tab. | true | | descriptionEnabled | Show “Description” field in settings. | true | | tagsEnabled | Show “Tags” field in settings. | true | | switchDesktopMobilePropsEnabled | Show mobile properties toggle. | true | | stepToOtherElementEnabled | Show buttons to jump to other elements. | true | | deleteButtonEnabled | Show delete element button. | true | | toggleSidePanel | Allow collapsing side panel. | true | | blocksSectionsShow | Show blocks menu. | true | | blocksEmptyEnabled | Show empty blocks. | true | | blocksSavedEnabled | Show saved blocks. | true | | blocksCommonEnabled | Show common blocks. | true | | blocksTemplateEnabled | Show template blocks. | true | | blocksSearchEnabled | Show blocks search. | true | | blocksAddPanelEnabled | Show add block panel in visual editor. | true | | imagePathDropdownEnabled | Show dropdown with image path. | true | | | | | | formFieldImageTitleEnabled | Show title field in image form. | true | | formFieldBorderEnabled | Show border controls. | true | | formFieldBorderRadiusEnabled | Show border radius controls. | true | | formFieldBoxShadowEnabled | Show shadow controls. | true | | formFieldVisibilityEnabled | Show element visibility controls. | true | | formFieldExportAsPictureEnabled | Show “export as image” toggle. | true | | | | | | formButtonFieldInsertImageEnabled | Show “insert image into text” button for button. | true | | formButtonFieldVerticalAlignEnabled | Show vertical alignment controls for button. | true | | formButtonFieldTextAlignEnabled | Show text alignment controls for button. | true | | formButtonFieldBackgroundImageEnabled | Show background image controls for button. | true | | formButtonFieldPaddingsEnabled | Show padding controls for button. | true | | formButtonFieldReplacerEnabled | Show replacer for button. | true | | | | | | formCellFieldVerticalAlignEnabled | Show vertical alignment controls for cell. | true | | formCellFieldBackgroundImageEnabled | Show background image controls for cell. | true | | formCellFieldPaddingsEnabled | Show padding controls for cell. | true | | formCellFieldSizeEnabled | Show width and height controls. | true | | | | | | formImageFieldVerticalAlignEnabled | Show vertical alignment controls for image. | true | | formImageFieldReplacerEnabled | Show replacer for image. | true | | formImageFieldHeightEnabled | Show height field for image. | true | | | | | | formTableFieldBackgroundImageEnabled | Show background image controls for table. | true | | formDivFieldBackgroundImageEnabled | Show background image controls for container. | true | | formEmailFieldBackgroundImageEnabled | Show background image controls for email. | true | | | | | | formTextFieldTypografEnabled | Show typograph button. | true | | formTextFieldReplacerEnabled | Show replacer button. | true | | | | | | elementImageEnabled | Element Image. | true | | elementTextEnabled | Element Text. | true | | elementHeaderEnabled | Element Heading. | true | | elementButtonEnabled | Element Button. | true | | elementListULEnabled | Element List UL. | true | | elementListOLEnabled | Element List OL. | true | | elementDividerEnabled | Element Divider. | true | | elementSpacerEnabled | Element Spacer. | true | | elementSocialEnabled | Element Social. | true | | elementTableEnabled | Element Table. | true | | elementCountdownEnabled | Element Countdown. | true | | elementVideoEnabled | Element Video. | true | | elementAIimageEnabled | Element AI image. | true | | elementAItextEnabled | Element AI text. | true | | elementCarouselEnabled | Element AMP carousel. | true | | elementAccordionEnabled | Element AMP accordion. | true | | elementFormEnabled | Element AMP form. | true | | | | | | imageCenterLocalUploadEnabled | Local file upload field in Image Center. | true | | imageCenterStockEnabled | Stock photos tab. | true | | imageCenterGifEnabled | Stock GIFs tab. | true | | imageCenterEditorEnabled | Image editor tab. | true | | compressMaxSize | Client-side compression max bytes in file manager (~5 MiB default). | see types | | compressMaxWidthOrHeight | Resize max width/height, px (2000 default). | see types |

Event wiring

Either pass callbacks to init, or call instance.handle*(listener, priority?) — typical pattern returns unsubscribe fn. Hooks may be async.

Save handlers (handleSaveEmail, handleSaveBlock, handleSaveComment) receive SaveEventPayload: { patch, value, prev?, source? }.

Subject / preheader use different subscription signatures — inspect useblocks.d.ts.

useblocks.init({
  element: '#test',
  content: { email: { id: '1' } },
  getAuthToken,
  handleReadEmail: async (id) => fetchEmail(id),
  handleSaveEmail: async (payload) => saveEmail(payload.value),
}).then((instance) => {
  const unsubscribe = instance.handleEmailChanged(async () => {});
  /* unsubscribe(); */
});

Events

See typings (ExportedApi.DataMixin.Events) — includes for example handleRemoveEmail, handleRemoveEmailAutoSave, handleReadCommonBlocks, handleReadTemplateBlocks, handleCloneEmail, handleShareEmail, handleLivePreviewEmail, handlePreviewEmail, handleValidate, handleSubjectChanged, handlePreheaderChanged, handleReadLocale, handleTranslate, handleLimitUsage, plus the rows below.

| Name | Summary | | ------------------------- | ------------------------------------ | | handleReadEmail | Load email by id (string) | | handleSaveEmail | Persist email (SaveEventPayload) | | handleReadEmailRevisions | Autosaves / revisions | | handleEmailAutosave | Autosave created | | handleReadBlocks | Project blocks | | handleSaveBlock | Save block | | handleRemoveBlock | Delete block | | handleReadComments | Email comments | | handleSaveComment | Save comment | | handleRemoveComment | Delete comment | | handleSaveButtonClick | Toolbar primary click | | handleNextButtonClick | “Next” click | | handlePreviousButtonClick | “Back” click | | handleEmailChanged | Email payload changed | | handleHtmlChanged | HTML string changed | | handleDestroy | Destroy lifecycle | | handleLoad | Instance ready hook | | handleLoadImage | Image upload helpers & proxies | | handleNotify | Generic notification | | handleError | Error toast hook | | handleSuccess | Success toast hook | | handleTestEmailSend | Send test mail | | handleTestEmailModal | Test send modal opened |

Methods

Exports on the module bundle: init, parseAMP, etc. Everything else below lives on useblocks.init()’s fulfilled instance:

| Method | Notes | | ------ | ----- | | show | Swap email content (Content) | | save | Trigger persistence pipeline | | getEmail | Current CompiledEmail | | compileEmail | Controlled compilation | | setEmailMeta | Merge meta only | | getBlocks / getComments / getEmailRevisions | Data snapshots | | getCodeErrors | Linter output | | getConfig / setConfig / updateConfig | UI config | | notify | Push notification | | getElement | Mount node | | destroy | Teardown (call on SPA unmount) | | reset | Re-init with new options | | undoRedoService | Undo/redo API |

📂 File Manager

useblocks.init({
  storageProvider: /* StorageProvider implementation */,
  config: {
    imageCenterFileManagerView: true,
  },
});

The fileManager section controls feature flags; every field is optional — default true when omitted unless noted in typings.

Basic Operations

• enableTrash — enables trash functionality for deleted files. When enabled, files are moved to trash instead of permanent deletion. Default: true
• enableRenameFolder — allows renaming folders. Default is true
• enableRenameFile — allows renaming files. Default is true
• enableUpdateFile — allows updating file content or metadata. Default is true
• enableEdit — allows editing files (changing content or properties). Default is true
• enableMoveFile — allows moving files between folders. Default is true
• enableMoveFolder — allows moving folders. Default is true
• enableCopyFile — allows copying files. Default is true
• enableCopyFolder — allows copying folders. Default is true
• enableDelete — allows deleting files and folders. When the recycle bin is enabled, files are moved there instead of being permanently deleted. Default is true
• multiSelect — allows multiple selection of files and folders for batch operations. Default is true
• defaultFolderName — default folder name
• sortOptions — whitelist of sort dropdown values ('date-desc' \| 'date-asc' \| 'size-desc' \| 'size-asc' \| 'name-asc' \| 'name-desc' \| 'type-asc'). If omitted or empty, all options supported by the file-manager package are shown. Use a non-empty array to hide sorts your platform does not implement (e.g. size or type).

Pagination & Display

• enablePagination — enables paginated navigation. If disabled, all items are loaded at once. Default: true

Client-Side Processing

• clientSideSorting — client-side file sorting.

  • If true, applies standard sorting (by name ascending).
  • If a function is provided, it receives the current file array, optional sortBy and sortOrder, and returns a sorted array.

• clientSidePaging — client-side file pagination.

  • If true, applies standard array slicing based on page and limit.
  • If a function is provided, it receives the file array, page and limit, and returns an array for the specific page only.

• clientSideFilter — client-side file filtering.

  • If true, applies standard filtering by search text.
  • If a function is provided, it receives the file array and optional search, and returns a filtered array.

Cache Strategy

• cacheStrategy — caching strategy for performance optimization.
  • ttl — cache time-to-live in milliseconds. Default: 300000 (5 minutes)
  • errorTtl — cache TTL for errors in milliseconds. Default: 60000 (1 minute)
  • allowSortedInsert — allows inserting elements into sorted arrays without full cache invalidation. Default: false
  • allowSearchInsert — allows inserting elements into filtered arrays without full cache invalidation. Default: false
  • invalidateOnPaginationFull — marks cache as stale when inserting into a full paginated page. Default: true
  • comparator — comparison function for sorting two files. Default: name-based comparison
  • filterMatch — function to check if a file passes current filters. Default: name-based search

Interface StorageProvider

Properties

| Property | Type | Description | Default | | --------------------------- | --------- | ----------------------------------------------- | ------- | | pathMode | boolean | Use path as identifier for folders | - | | rootId | string | Custom identifier for root folder | '' | | trashPath | string | Path to trash/recycle bin folder | - | | tempPath | string | Path to temporary folder for uploads | - | | useSoftDelete | boolean | Enable client-side soft delete | false | | ensureFolderTrailingSlash | boolean | Add a trailing slash to folder paths | true | | validateDuplicates | boolean | Client-side check for existing files or folders | - |

Methods

Core Methods

| Method | Parameters | Returns | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | getItems | options:- folderId?: string- search?: string- sortBy?: string- sortOrder?: 'asc'\|'desc'- page?: number- limit?: number- itemType: 'all'\|'file'\|'folder' | { items: FileSystemItem[], pagination?: Partial<ApiPaginationResponse> } | Retrieve files/folders with filtering, sorting, pagination | | createFolder | name: string, parentid?: string | FileSystemItem | Create new folder | | uploadFile | file: - name: string- size: number- type: string- folderId?: string- data: Blob \| string- thumbnail?: string- dimensions?: string- aspectRatio?: string- extension?: string | FileSystemItemUpdate | Upload file with metadata | | uploadFiles | request:- items: { requestId?: string, name: string, size: number, type: string, folderId?: string \| null, data: Blob \| string, extension?: string }[]- folderId?: string \| null | BatchResult<UploadFileResultData> | Upload multiple files. The order of items matters — if requestId is not provided, results are matched by index | | uploadFileByUrl | url: string, folderId?: string | FileSystemItem | Upload file from URL (check for existing files) | | findItemByPath | path: string | FileSystemItem \| undefined | Find system files/folders by path | | setController | controller: StorageProviderController | void | Set cache management controller | | getFileData | file: FileSystemItem | Blob | Get file content as blob | | getUrl | file: FileSystemItem | string | Get file access URL | | getThumbnailUrl | file: FileSystemItem | string | Get thumbnail URL | | renameItem | item: FileSystemItem, newName: string | FileSystemItemUpdate | Rename file/folder | | deleteItem | item: FileSystemItem | void | Delete single item (moves to trash if soft delete enabled) | | deleteItems | items: FileSystemItem[] | BatchResult<never> | Delete multiple items | | moveItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Move single item | | moveItems | items: FileSystemItem[], targetFolderId?: string | BatchResult<FileSystemItemUpdate> | Move multiple items | | copyItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Copy single item | | copyItems | items: FileSystemItem[], targetFolderId?: string | BatchResult<FileSystemItemUpdate> | Copy multiple items | | updateFile | file: FileSystemItem, updates: metadata object | FileSystemItemUpdate | Update file metadata/content |

Type Definitions

• MayBePromise<T>: T | Promise<T>
• FileSystemItem: File or folder object
• FileSystemItemUpdate: Item with changed fields
• BatchResult<T>: Result with success/failure details
• ApiPaginationResponse: Pagination metadata

Important Notes

• Soft Delete: When useSoftDelete=true, delete operations move items to trashPath
• Root Folder: Use rootId or empty string for root operations
• Path Resolution: trashPath and tempPath are resolved to actual folder IDs
• URL Upload: Should check if file already exists on current server
• Cache Control: Use setController for cache invalidation requests
• Double soft delete: If your backend already implements soft delete, keep useSoftDelete=false