Quickstart

This quickstart guide will help you create and run your first add-on, a simple hello world add-on built with plain JavaScript.

Introduction

Check out this short video below to get a quick visual introduction to the steps you'll be taking to create your very first add-on.

Prerequisites

NodeJS (major version of 16 or greater) and npm (major version of 8 or greater) installed
Familiarity with programming in HTML, CSS and JavaScript
An Adobe Express account (use an existing Adobe ID or simply create one for free).

Add-on CLI

The Adobe Express add-on CLI (Command Line Interface) is required for add-on development and allows you to create and host Adobe Express add-ons directly from your local machine.

Step 1: Create your add-on project

Open your terminal and run the following command:

npx @adobe/create-ccweb-add-on hello-world --template javascript-with-document-sandbox     
Copied to your clipboard
npx @adobe/create-ccweb-add-on hello-world --template javascript-with-document-sandbox

This command will create a new add-on based on pure JavaScript with Document Sandbox support (the set of APIs that allow you to interact with Adobe Express documents).

hello-world is the name of the add-on you are creating.
The --template flag specifies the template to use for the add-on; in this case, javascript-with-document-sandbox. The parameter is optional, and when missing, the CLI will prompt you to choose one from a list.

The Templates section on the Development Tools page provides a list of available options; if your add-on doesn't need to manipulate documents, you may want to pick a sandbox-free template (e.g., javascript instead of javascript-with-document-sandbox).

For Windows Users: If you're using the CLI in the terminal, you'll need to add openssl to the path under Environment Variables. If git is installed, openssl can be found at C:\Program >Files\Git\usr\bin. Otherwise, you can download git from https://git-scm.com/downloads, and add the directory location to the path variable in your Environment Variables.

npx is an npm package runner that can execute packages without installing them explicitly.

Please run this command to clear the npx cache and ensure the latest version of the CLI is invoked.

npx clear-npx-cache
npx @adobe/create-ccweb-add-on hello-world 
Copied to your clipboard
npx clear-npx-cache
npx @adobe/create-ccweb-add-on hello-world

The above may prove useful when updated version of the CLI are released. If you want to read each individual CLI command manual pages, run them via npx with the --help flag, for example:

npx @adobe/ccweb-add-on-scripts start --help  
Copied to your clipboard
npx @adobe/ccweb-add-on-scripts start --help

Step 2: Build and start your add-on

Next, execute the following commands to change into the newly created hello-world add-on folder, build the add-on, and start the add-on in a local server:

cd hello-world;
npm run build;
npm run start;
Copied to your clipboard
cd hello-world;
npm run build;
npm run start;

The start script will display messages like the following after it executes:

Done. Your add-on 'hello-world' is hosted on: https://localhost:5241/

You can now sideload your add-on by enabling the Developer Mode in the Add-ons panel.
Copied to your clipboard
Done. Your add-on 'hello-world' is hosted on: https://localhost:5241/

You can now sideload your add-on by enabling the Developer Mode in the Add-ons panel.

Step 3: Enable add-on development mode (first-time only)

Navigate to Adobe Express.
Click on your user avatar in the top righthand corner and choose Settings.
Click the toggle button for Add-on Development to enable the add-on development and distribution tools:

Step 4: Load and run your add-on

Navigate your browser to Adobe Express and create a new project.
Click the Add-ons icon in the left rail.
Notice there are two tabs, Discover and Your add-ons.
Click on the Your add-ons tab to access the Add-on Development tools panel, and toggle on the radio Add-on testing toggle button.
Once clicked, a modal will appear where you will provide the URL of your locally hosted add-on.
Note: Use the default https://localhost:5241 supplied unless you are intentionally using a different port.
Check the I understand the risks of loading an add-on from an external server checkbox and press the Connect button.
The Add-on Development panel will expand and show a message that the add-on is connected in the log, along with the name and version of your add-on. Click on the down arrow icon to collapse the panel:
To run your add-on, simply click on it from the In development panel. Your add-on should now be displayed in the add-ons panel on the right side of your Adobe Express window:

Step 5: Edit your add-on

Now, while your add-on is still loaded and running, open the src/index.html file and update the "Click me" string in the <button> below:

vs code click me

to "Say hello":

vs code say hello

Note the terminal where your add-on is running will display messages showing that the src has been rebuilt like below. This is due to the hot module reload feature built into the CLI.

hot reload

Go back to your browser where your add-on is running in Adobe Express, and notice the new string is automatically shown, and the Add-on Development panel shows that it was auto-reloaded:

updated add-on

You can continue to update your code while your add-on is running and the add-on will automatically be rebuilt.

Manifest updates
Any changes to your manifest.json will require a manual reload of your add-on. The Add-on Development panel will indicate this in the log messages, and the Refresh button can be used to reload the add-on directly within Adobe Express. You can try this by updating the name field in the src/manifest.json file of your running add-on to "Say hello", for instance:

manifest update

Then, switch back to your Adobe Express window and you should see a message that changes have been detected in your manifest, such as below:

manifest refresh reminder

Click the Refresh button, then click your add-on icon to load it again, and note the updated name in the title of your add-on as outlined below:

manifest refresh complete

Next steps

Congratulations! You've completed the quickstart and run your first add-on!

Next, check out the development tools page to discover more details on topics to be aware of while building add-ons, followed by the rest of the guides section, where you will find in-depth resources for designing, developing, debugging and distributing your add-ons.

If you're ready to dive into our developer platform, we highly recommend following the tutorials, and exploring our collection of code samples. These samples provide hands-on examples of how to use our platform SDKs and APIs, and are a great resource to help you get started building your own add-ons.

Overview

Development tools