Edit in GitHubLog an issue

Development Tools

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):

ArgumentOptionalDefault ValueDescription
add-on-name
No
Name of the add-on. A new add-on project with this argument will be created in the user's current working directory.
template
Yes
none, you will
be prompted from the CLI
The template to use for creating the add-on.
verbose
Yes
false
Setting this argument enables the verbose flag on the underlying operations.

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

Copied to your clipboard
npx @adobe/create-ccweb-add-on my-addon --template react-typescript --verbose

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:

ArgumentOptionalDefault ValueDescription
src
Yes
src
Directory where the source code and assets for the add-on is present.
use
Yes
Transpiler/bundler to be used. For example, webpack.
port
Yes
5241
Local development server port.
verbose
Yes
false
Setting this argument enables the verbose flag on the underlying operations.

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

Copied to your clipboard
npm run start -- --port 8080

To specify you want to use webpack AND port 8080:

Copied to your clipboard
npm run start -- --use webpack --port 8080
Copied to your clipboard
"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. The table below summarizes the templates and their associated frameworks.


TemplateFramework
javascript
JavaScript
swc-javascript
JavaScript with Spectrum Web Components support
swc-typescript
TypeScript with Spectrum Web Components support
react-javascript
React with JavaScript
react-typescript
React with TypeScript

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

TemplateDescription
javascript-with-document-sandbox
JavaScript with Document Sandbox support.
swc-javascript-with-document-sandbox
JavaScript and Spectrum Web Components with Document Sandbox support.
swc-typescript-with-document-sandbox
TypeScript and Spectrum Web Components with Document Sandbox support.
react-javascript-with-document-sandbox
React and JavaScript with Document Sandbox support.
react-typescript-with-document-sandbox
React and TypeScript with Document Sandbox support.

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

Copied to your clipboard
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:

Copied to your clipboard
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:

Copied to your clipboard
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:

doc sandbox prompt

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.

cli doc sandbox prompt

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

template scaffolding message

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:

CLI completed message

Manifest

A manifest.json file is required in every add-on project. The manifest provides details including important metadata about your add-on and how it should behave. Be sure to consult the manifest schema reference to ensure that your manifest.json file is properly formatted and includes all of the necessary properties and values.

Add-on Development Tools Panel

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:

add-ons tools screenshot manifest error screenshot

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.