Add-on Development Terminology

A comprehensive guide to Adobe Express add-on terminology, SDKs, runtimes, and development concepts.

Core Terms

Overloaded Terms Clarification

Many terms in Adobe Express add-on development have multiple meanings depending on context. This table clarifies the different uses to prevent confusion.

Common Sources of Confusion

"I need to access the document" - Which document?

• Adobe Express user's project → "The document has 3 pages"
• Manipulate Adobe Express content → editor.documentRoot
• Import/export Adobe Express document → addOnUISdk.app.document
• Your add-on's UI HTML page → document.getElementById()

"What's the DOM?" - Which DOM?

• Your add-on's HTML structure → document.querySelector() (Browser DOM)
• Adobe Express's document structure → Use "scenegraph" not "DOM"

"How do I use the runtime?" - Which runtime?

• Execution environment → "Code runs in iframe runtime or document sandbox"
• Communication APIs → addOnUISdk.instance.runtime or addOnSandboxSdk.instance.runtime

"What is the context?" - Which context?

• Execution environment → "The iframe context has standard Web APIs"
• Editor's selection/insertion → editor.context.selection
• Security boundaries → See iframe Context & Security

"What does instance mean?" - Which instance?

• SDK property → addOnUISdk.instance or addOnSandboxSdk.instance
• Class object → "rectangle is an instance of RectangleNode"
• Running session → "User's add-on instance"

"How do I import SDKs?" - Named or default export?

• Add-on UI SDK → Default export (no curly braces): import addOnUISdk from "..."
• Document Sandbox SDK → Default export (no curly braces): import addOnSandboxSdk from "..."
• Express Document SDK → Named exports (requires curly braces): import { editor, colorUtils } from "..."

"Are Web APIs and Browser APIs the same?" - Yes!

• Same thing, different names → "Web APIs" = "Browser APIs"
• iframe runtime → Standard Web APIs available
• Document sandbox → Limited Web APIs only (console, Blob)

"Should I say node or element?" - It depends!

• Adobe Express scenegraph → Use "node" (RectangleNode, TextNode, etc.) to describe visual elements in the document
• Your add-on's HTML → Use "DOM node" or "HTML element"
• User-facing docs → "element" is okay (e.g., "text elements in your design")
• Developer docs → Prefer "node" for precision and to match API class names

"Should I use addOnUISdk.instance or addOnUISdk.app?" - Different scopes

• Add-on scope (instance) → Features specific to YOUR add-on
  • instance.runtime - YOUR add-on's communication
  • instance.clientStorage - YOUR add-on's storage (per-user, per-addon)
  • instance.manifest - YOUR add-on's configuration
• Application scope (app) → Features shared across Adobe Express
  • app.document - The Adobe Express document (same for all add-ons)
  • app.currentUser - The Express user (not specific to your add-on)
  • app.ui - Adobe Express UI state (theme, locale)

Runtime Environments

Adobe Express add-ons use a dual-runtime architecture with two separate JavaScript execution environments:

Iframe Runtime

• What it is: A sandboxed iframe environment where your add-on's user interface runs
• Purpose: Hosts your HTML, CSS, and JavaScript UI code
• SDK Used: Add-on UI SDK
• File reference: Typically your index.html and associated UI JavaScript files
• Security: Sandboxed for security with standard Web APIs (some features require manifest permissions)
• Also known as: "Panel Runtime", "iframe Sandbox"
• Terminology Note: While the browser term is "iframe sandbox" (as used in HTML sandbox attributes and manifest permissions), we use "iframe runtime" throughout the documentation for consistency with "document sandbox runtime" and to distinguish between the two execution environments

Document Sandbox

• What it is: A separate sandboxed JavaScript environment for document manipulation
• Purpose: Provides secure access to Adobe Express document structure and content
• SDKs Used: Document Sandbox SDK (for communication) + Express Document SDK (for document APIs)
• File reference: Specified in your manifest's documentSandbox entry (e.g., code.js)
• Security: Isolated environment with limited Web APIs but direct document access
• Also known as: "Document Model Sandbox"

Understanding Runtime Communication

The two runtimes communicate with each other through the Communication APIs, allowing your UI to trigger document changes and vice versa.

About Web APIs: The terms "browser capabilities," "browser features," and "Web APIs" all refer to the standard JavaScript APIs available in web environments (like fetch, localStorage, console, Blob, etc.). The iframe runtime has standard Web APIs, while the document sandbox has limited Web APIs for security reasons. See the Web APIs Reference for details on what's available in each environment.

SDK Concepts

Add-on UI SDK

addOnUISdk: The JavaScript module you import in your iframe code that provides runtime instance, app interfaces, constants, and UI-specific APIs.

The addOnUISdk object provides two distinct scopes of functionality:

addOnUISdk.instance - Add-on Scope
Features specific to your individual add-on:

• runtime - Communication between your add-on's iframe and document sandbox
• clientStorage - Data storage for your add-on only (per-user, per-addon)
• manifest - Your add-on's configuration
• entrypointType - Your add-on's current entry point
• logger - Logging for your add-on

Scope: Isolated to your add-on instance; doesn't interact with other add-ons.

addOnUISdk.app - Application Scope
Features shared across Adobe Express (the host application):

• document - The active Adobe Express document (shared across all add-ons)
• oauth - Authentication with external services
• currentUser - The Adobe Express user (not specific to your add-on)
• ui - Adobe Express UI state (theme, locale, etc.)
• command - Commands in the host application

Scope: Interacts with Adobe Express itself and its global state.

Express Document SDK

Express Document SDK (express-document-sdk): The JavaScript module providing document manipulation capabilities for the document sandbox. Import named exports: editor, colorUtils, constants, fonts, viewport.

Document Sandbox SDK

Document Sandbox SDK (add-on-sdk-document-sandbox): The JavaScript module for communication between iframe runtime and document sandbox. Import as addOnSandboxSdk. Only needed when you require bi-directional communication between the two environments.

Import Patterns & Usage

Complete Import Reference

Copy
// iframe runtime (UI code) - index.js/index.html
import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Document sandbox runtime (content manipulation) - code.js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";  // For communication
import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk";  // For document APIs

// Add-on UI SDK with explicit constants
import addOnUISdk, { Range, RenditionFormat, Variant } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
Copied to your clipboard
// iframe runtime (UI code) - index.js/index.html
import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Document sandbox runtime (content manipulation) - code.js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";  // For communication
import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk";  // For document APIs

// Add-on UI SDK with explicit constants
import addOnUISdk, { Range, RenditionFormat, Variant } from "https://express.adobe.com/static/add-on-sdk/sdk.js";

When to Use Each Import

Communication System

Bidirectional Communication Pattern

iframe runtime → document sandbox:

Copy
// iframe runtime (index.js)
const { runtime } = addOnUISdk.instance;
const sandboxProxy = await runtime.apiProxy("documentSandbox");
await sandboxProxy.createRectangle();

// document sandbox (code.js)
const { runtime } = addOnSandboxSdk.instance;  // Document Sandbox SDK
runtime.exposeApi({
    createRectangle() {
        const rect = editor.createRectangle();
        editor.context.insertionParent.children.append(rect);
    }
});
Copied to your clipboard
// iframe runtime (index.js)
const { runtime } = addOnUISdk.instance;
const sandboxProxy = await runtime.apiProxy("documentSandbox");
await sandboxProxy.createRectangle();

// document sandbox (code.js)
const { runtime } = addOnSandboxSdk.instance;  // Document Sandbox SDK
runtime.exposeApi({
    createRectangle() {
        const rect = editor.createRectangle();
        editor.context.insertionParent.children.append(rect);
    }
});

document sandbox → iframe runtime:

Copy
// document sandbox (code.js)
const panelProxy = await runtime.apiProxy("panel");
await panelProxy.updateUI("Rectangle created");

// iframe runtime (index.js)
runtime.exposeApi({
    updateUI(message) {
        document.getElementById('status').textContent = message;
    }
});
Copied to your clipboard
// document sandbox (code.js)
const panelProxy = await runtime.apiProxy("panel");
await panelProxy.updateUI("Rectangle created");

// iframe runtime (index.js)
runtime.exposeApi({
    updateUI(message) {
        document.getElementById('status').textContent = message;
    }
});

Runtime Types

• panel: The main iframe runtime for your add-on UI
• documentSandbox: The document manipulation runtime
• dialog: Runtime context when code is running within a modal dialog

Core Development Objects

editor Object

Primary interface for document manipulation in the document sandbox.

Copy
import { editor } from "express-document-sdk";

const rectangle = editor.createRectangle();
const textNode = editor.createText("Hello World");
const insertionParent = editor.context.insertionParent;
Copied to your clipboard
import { editor } from "express-document-sdk";

const rectangle = editor.createRectangle();
const textNode = editor.createText("Hello World");
const insertionParent = editor.context.insertionParent;

constants

Type-safe values for SDK operations that prevent string literal errors.

Copy
// UI SDK Constants
await addOnUISdk.app.document.createRenditions({
    range: Range.currentPage,
    format: RenditionFormat.png
});

// Document Sandbox Constants
rectangle.fill = {
    type: constants.FillType.color,
    color: { red: 1, green: 0, blue: 0, alpha: 1 }
};
Copied to your clipboard
// UI SDK Constants
await addOnUISdk.app.document.createRenditions({
    range: Range.currentPage,
    format: RenditionFormat.png
});

// Document Sandbox Constants
rectangle.fill = {
    type: constants.FillType.color,
    color: { red: 1, green: 0, blue: 0, alpha: 1 }
};

ColorUtils

Utility functions for creating and converting colors in the document sandbox.

Copy
import { colorUtils } from "express-document-sdk";

const redColor = colorUtils.fromRGB(1, 0, 0);           // RGB values (0-1)
const blueColor = colorUtils.fromHex("#0066CC");        // Hex string
const hexString = colorUtils.toHex(redColor);           // "#FF0000FF"
Copied to your clipboard
import { colorUtils } from "express-document-sdk";

const redColor = colorUtils.fromRGB(1, 0, 0);           // RGB values (0-1)
const blueColor = colorUtils.fromHex("#0066CC");        // Hex string
const hexString = colorUtils.toHex(redColor);           // "#FF0000FF"

Node Hierarchy

Adobe Express documents are structured as a scenegraph - a hierarchical tree of nodes representing visual elements.

BaseNode: The minimal base class for all document elements with basic properties like id, type, parent, allChildren.

Node: Full-featured visual content that extends BaseNode with visual properties and transformations.

Common Node Types:

• Container Nodes: ArtboardNode, GroupNode, PageNode (hold other elements)
• Content Nodes: RectangleNode, EllipseNode, TextNode, LineNode, PathNode (visual elements)
• Media Nodes: MediaContainerNode, ImageRectangleNode (images and media)

Copy
// Navigate the document hierarchy
const root = editor.documentRoot;           // ExpressRootNode
const currentPage = root.pages.first;       // PageNode
const artboard = currentPage.artboards.first; // ArtboardNode

// Create and add content
const rectangle = editor.createRectangle(); // RectangleNode
artboard.children.append(rectangle);
Copied to your clipboard
// Navigate the document hierarchy
const root = editor.documentRoot;           // ExpressRootNode
const currentPage = root.pages.first;       // PageNode
const artboard = currentPage.artboards.first; // ArtboardNode

// Create and add content
const rectangle = editor.createRectangle(); // RectangleNode
artboard.children.append(rectangle);

Development Environment & Tools

Add-on Marketplace

Distribution platform where users discover and install add-ons within Adobe Express via the "Add-ons" button in the left sidebar.

Code Playground

Interactive browser-based development environment for experimenting with add-on APIs without local setup. See the Code Playground guide for more details.

Adobe Express Add-on CLI

Command Line Interface tool for creating, building, and packaging add-ons for local development.

• Installation: npm install -g @adobe/ccweb-add-on-cli
• Common Commands: create, start, build, package

See the Adobe Express Add-on CLI guide for more details.

MCP Server (Model Context Protocol)

AI-assisted development tool that enhances LLM responses with Adobe Express add-on documentation and TypeScript definitions.

• Purpose: Provide semantic documentation search and accurate code suggestions through AI assistants
• Requirements: Node.js 18+ and MCP-compatible IDE (Cursor, VS Code, Claude Desktop)

See the Adobe Express Add-on MCP Server guide for more details.

Add-on Development Mode

Special mode in Adobe Express (Settings > Add-on Development toggle) that allows loading and testing local add-ons during development. See Add-on Development Mode for more details.

Manifest Configuration

Copy
{
  "entryPoints": [
    {
      "type": "panel",
      "id": "panel1",
      "main": "index.html",           // iframe runtime entry
      "documentSandbox": "code.js"    // document sandbox entry (optional)
    }
  ],
  "permissions": {
    "sandbox": ["allow-popups", "allow-downloads"],
    "oauth": ["www.dropbox.com", "api.example.com"]
  }
}
Copied to your clipboard
{
  "entryPoints": [
    {
      "type": "panel",
      "id": "panel1",
      "main": "index.html",           // iframe runtime entry
      "documentSandbox": "code.js"    // document sandbox entry (optional)
    }
  ],
  "permissions": {
    "sandbox": ["allow-popups", "allow-downloads"],
    "oauth": ["www.dropbox.com", "api.example.com"]
  }
}

Quick Decision Guide

Building a UI Panel? → Add-on UI SDK (addOnUISdk)
Creating new content? → Document APIs (in Document Sandbox, via editor)
Modifying existing content? → Document APIs (in Document Sandbox, via editor)
Connecting UI to Document? → Communication APIs (runtime.exposeApi(), runtime.apiProxy())
Need browser features in sandbox? → Web APIs or proxy from iframe

Troubleshooting Common Issues

Import Errors

Copy
// ✅ Correct patterns
import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";  // Default export (no curly braces)
import addOnSandboxSdk from "add-on-sdk-document-sandbox";                     // Default export (no curly braces)
import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk";  // Named exports (requires curly braces)

// ❌ Common mistakes
import { addOnUISdk } from "..."; // Wrong: should be default import (no curly braces)
import addOnSandboxSdk from "add-on-ui-sdk"; // Wrong: mixed up the SDKs
import editor from "express-document-sdk"; // Wrong: should be named import (needs curly braces)
Copied to your clipboard
// ✅ Correct patterns
import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";  // Default export (no curly braces)
import addOnSandboxSdk from "add-on-sdk-document-sandbox";                     // Default export (no curly braces)
import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk";  // Named exports (requires curly braces)

// ❌ Common mistakes
import { addOnUISdk } from "..."; // Wrong: should be default import (no curly braces)
import addOnSandboxSdk from "add-on-ui-sdk"; // Wrong: mixed up the SDKs
import editor from "express-document-sdk"; // Wrong: should be named import (needs curly braces)

Runtime Context

"undefined" Errors

Problem: addOnUISdk.constants.SomeConstant returns undefined
Solution: Some constants require explicit imports. Check the Constants Reference

FAQs

Q: What's the difference between "Add-on UI SDK" and "Document APIs"?

A: The Add-on UI SDK runs in the iframe runtime and handles UI, user interactions, and import/export. Document APIs (via Express Document SDK) run in the document sandbox and handle content creation and document manipulation.

Q: Why are there two different runtime environments?

A: Security and performance. The iframe runtime is sandboxed for security but has standard Web APIs. The document sandbox has direct access to Adobe Express's document engine but limited Web APIs.

Q: Can I use Document APIs directly from the iframe runtime?

A: No, Document APIs (Express Document SDK) are only available in the document sandbox for security reasons. You must use the communication system (Document Sandbox SDK) to bridge between environments.

Q: When do I use addOnUISdk vs addOnSandboxSdk?

A: Use addOnUISdk (Add-on UI SDK) in your iframe runtime code (usually index.html or ui/ folder). Use addOnSandboxSdk (Document Sandbox SDK) in your document sandbox code (usually code.js or sandbox/ folder).

Q: I see references to "UI SDK" - is this different from "Add-on UI SDK"?

A: No, they're the same. "Add-on UI SDK" is the full, preferred term for clarity, but "UI SDK" is commonly used as shorthand throughout the documentation.

Q: What's the difference between addOnUISdk.instance and addOnUISdk.app?

A: These represent different scopes of functionality:

• addOnUISdk.instance - Add-on scope: Features specific to YOUR add-on

  • instance.runtime - Communication for YOUR add-on
  • instance.clientStorage - Storage for YOUR add-on only (per-user, per-addon)
  • instance.manifest - YOUR add-on's configuration

• addOnUISdk.app - Application scope: Features shared across Adobe Express

  • app.document - The Adobe Express document (same for all add-ons)
  • app.currentUser - The Express user (not specific to your add-on)
  • app.ui - Adobe Express UI state (theme, locale)

Use instance for add-on-specific features; use app to interact with Adobe Express itself.

Q: I'm confused by terms like "document", "context", "runtime", and "instance" - they seem to mean different things in different places?

A: Yes! Many terms in add-on development are overloaded with multiple meanings. Check the Overloaded Terms Clarification table at the top of this page for complete clarification. For example, "document" can mean:

• The Adobe Express user's project
• editor.documentRoot (scenegraph manipulation)
• addOnUISdk.app.document (import/export operations)
• Browser DOM document object (your add-on's HTML)

This table provides all meanings with examples for 17 commonly overloaded terms.

Q: What is the singleton pattern and why do add-on SDKs use it?

A: All Adobe Express add-on SDKs use the singleton pattern - they provide pre-instantiated objects you import and use directly. You never create new instances yourself.

This ensures all your code works with the same SDK instances, preventing conflicts and maintaining consistent state. For Express Document SDK specifically, you import lowercase names (editor, colorUtils, constants, fonts, viewport) which are singleton objects, NOT the uppercase class names (Editor, ColorUtils, etc.).

See the Architecture Guide for complete details.

Related Documentation

• Adobe Express Add-ons Developer Guide - Official documentation and getting started guide
• Add-on Architecture Guide - Comprehensive guide with visual diagrams
• Add-on UI SDK Reference
• Document Sandbox Overview
• Communication APIs
• Add-on UI SDK Constants Usage Guide
• Document Sandbox Constants Usage Guide

Last updated 10/22/2025

Was this helpful?

Yes

No