Development Tools

This section provides a set of guides to help you in the development stage of your add-on.

Using the CLI

The add-on CLI (Command Line Interface) is the main tool that enables you to develop, test, and package add-ons for our platform. With the add-on CLI, you can create a new add-on project, build and test your add-on locally, and package your add-on for distribution.

Here are some key features of the add-on CLI:

• Project creation: The add-on CLI provides a command to create a new add-on project with a basic file structure and configuration.
• Local development: The add-on CLI includes a built-in server that allows you to test your add-on locally before deploying it to our platform.
• Live reloading: The add-on CLI watches your project files for changes and automatically reloads the server when a change is detected.
• Packaging: The add-on CLI provides a command to package your add-on for distribution, including creating a ZIP file that can be uploaded to our platform.

CLI create options

The table below shows the list of arguments that can be specified with the CLI create command (ie: npx @adobe/create-ccweb-add-on):

For instance, the following command would specify all possible arguments:

npx @adobe/create-ccweb-add-on my-addon --template react-typescript --verbose

data-slots=heading, text1, text2, text3, text4, text5

data-variant=info

npx clear-npx-cache
npx @adobe/create-ccweb-add-on my-addon

npx @adobe/ccweb-add-on-scripts start --help

start script options

The table below shows a list of arguments that can be specified with the start script on your add-on project, which starts up the add-on in a local server:

For instance, to specify a port of 8080 instead, use the following command:

npm run start -- --port 8080

To specify you want to use webpack AND port 8080:

npm run start -- --use webpack --port 8080

data-slots=text

data-variant=info

"scripts": {
    "clean": "ccweb-add-on-scripts clean",
    "build": "ccweb-add-on-scripts build --use webpack",
    "start": "ccweb-add-on-scripts start --use webpack"
}

Templates

The add-on CLI contains built-in, pre-configured templates to allow you to create an add-on project based on your favorite development stack in the quickest possible manner. There are currently five base template options based on popular web development trends.

For a comprehensive comparison of all templates, detailed file structures, and guidance on choosing the right template for your project, see the Add-on Project Anatomy & CLI Templates guide.

The table below summarizes the templates and their associated frameworks. <br/>

As well as the following five template options, which include support for the Document Sandbox APIs:

You can supply any of the above template names after the --template parameter:

npx @adobe/create-ccweb-add-on <add-on-name> --template <template>

For instance, the following is an example of a command that will create an add-on based on the react-javascript template:

npx @adobe/create-ccweb-add-on helloworld-react-js --template react-javascript

and below is how you could specify the react-javascript-with-document-sandbox template:

npx @adobe/create-ccweb-add-on helloworld-react-js-doc-sandbox --template react-javascript-with-document-sandbox

No template parameter

The template parameter is optional, and the CLI will prompt you to choose from a list of template options if it's excluded. For instance, if you use just the base CLI command:

npx @adobe/create-ccweb-add-on <add-on-name>

you will see the following prompt from the CLI:

which shows the five base template options to choose from, followed by a prompt to ask if you want to add the Document Sandbox support once you choose the base template.

You will also see a message in the CLI output notifying you of which template the project was scaffolded with for reference:

data-slots=text1, text2

data-variant=warning

When the scaffolding is complete, you will see the following message, prompting you to navigate to the newly created project directory and start the local development scripts:

Sideload your add-on

After the add-on has been scaffolded and—as the screenshot above suggests—you have to run these commands in the newly created project directory:

npm run build
npm run start

This will build the add-on and start a local server, which you can then sideload into Adobe Express by clicking the button below.

data-slots= buttons

data-width=100%

data-isCentered=

data-variantsTypePrimary=primary

data-variantStyleFill=outline

data-className=code-playground-button-inline

The CLI will also display a https://www.adobe.com/go/addon-cli URL that you can option-click (if you're using the VSCode/Cursor Terminal) or copy and paste to open the Add-on Development window in Adobe Express.

You can also sideload it manually by following the steps below.

data-slots=list

data-summary=Click to view a list of steps to sideload an add-on in Adobe Express

It's possible to achieve the same result when a document is already open clicking the Add-ons icon on the left hand rail, then browse to Your add-ons and switch on Add-on testing.

data-slots=text, text2

data-variant=warning

If you run into the error below, you can follow the steps in the Known Issues & Limitations guide to fix it.

Add-on Development mode

Before you can build add-ons, Add-on Development mode in Adobe Express needs to be enabled—you only need to do this once.

data-slots=text

data-variant=success

data-slots=list

data-repeat=4

data-summary=Click to view a list of steps to manually enable the Developer Mode

The Add-on Development tools panel provides useful logging details indicating the status of your add-on, as well as action buttons to allow for refreshing and clearing the data associated with your add-on. The panel is shown in the screenshots below for reference:

data-slots=text

data-variant=info

Debugging

Messages logged in the Console by your add-on will be prefixed with [Add-on: <add-on-name>] to help you distinguish them from other messages.

Open the browser's developer tools by right-clicking on the browser window where Adobe Express is running, and selecting Inspect from the context menu. In the Console, you can filter out the messages from the Code Playground by typing just [Add-on: in the filter input.

Updating old projects

If you have an old project that you're updating, you must add the following script to your index.html file:

<head>
  <!-- ... -->
  <script type="module" src="add-on-console-override.js"></script>
</head>

Newer versions of the CLI, in their build command, will automatically provide the add-on-console-override.js file. Adding this script tag overrides the Console object and provides appropriately prefixed logs to your add-on project.