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

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

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

Copy
npx clear-npx-cache
npx @adobe/create-ccweb-add-on my-addon 
Copied to your clipboard
npx clear-npx-cache
npx @adobe/create-ccweb-add-on my-addon 

Copy
npx @adobe/ccweb-add-on-scripts start --help  
Copied to your clipboard
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:

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

To specify you want to use webpack AND port 8080:

Copy
npm run start -- --use webpack --port 8080
Copied to your clipboard
npm run start -- --use webpack --port 8080

Copy
"scripts": {
    "clean": "ccweb-add-on-scripts clean",
    "build": "ccweb-add-on-scripts build --use webpack",
    "start": "ccweb-add-on-scripts start --use webpack"
}
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.

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:

Copy
npx @adobe/create-ccweb-add-on <add-on-name> --template <template>
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:

Copy
npx @adobe/create-ccweb-add-on helloworld-react-js --template react-javascript
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:

Copy
npx @adobe/create-ccweb-add-on helloworld-react-js-doc-sandbox --template react-javascript-with-document-sandbox
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:

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:

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:

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:

Last updated 12/5/2023

Was this helpful?

Yes

No