From 1709d10b8d7e6f1dc5434b0d0576a8e8b9afe947 Mon Sep 17 00:00:00 2001 From: finnegan Date: Mon, 9 Sep 2024 18:44:14 -0400 Subject: [PATCH 1/7] created code playground page --- .../guides/getting_started/code_playground.md | 186 + yarn.lock | 6386 +++++------------ 2 files changed, 1819 insertions(+), 4753 deletions(-) create mode 100644 src/pages/guides/getting_started/code_playground.md diff --git a/src/pages/guides/getting_started/code_playground.md b/src/pages/guides/getting_started/code_playground.md new file mode 100644 index 000000000..23e73deee --- /dev/null +++ b/src/pages/guides/getting_started/code_playground.md @@ -0,0 +1,186 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Express Editor + - Adobe Express + - Add-on SDK + - SDK + - JavaScript + - Extend + - Extensibility + - API + - Add-on Manifest +title: Quickstart +description: This is the Quickstart page +contributors: + - https://github.com/hollyschinsky + - https://github.com/undavide +--- + +# 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`): + +| Argument | Optional | Default Value | Description | +| ------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `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: + +```bash +npx @adobe/create-ccweb-add-on my-addon --template react-typescript --verbose +``` + + + +#### CLI troubleshooting + +See the [templates](#templates) section for the currently supported template values. + +`npx` is an `npm` package runner that can execute packages without installing them explicitly. If needed, please run this command to clear the `npx` cache to ensure the latest version of the CLI is invoked. + +```bash +npx clear-npx-cache +npx @adobe/create-ccweb-add-on my-addon +``` + +The above may prove useful when updated versions of the CLI are released. If you want to read each individual CLI command manual page, run them via `npx` with the `--help` flag, for example: + +```bash +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: + +| Argument | Optional | Default Value | Description | +| --------- | -------- | ------------- | ---------------------------------------------------------------------------- | +| `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: + +```bash +npm run start -- --port 8080 +``` + +To specify you want to use `webpack` AND port `8080`: + +```bash +npm run start -- --use webpack --port 8080 +``` + + + +The extra arguments are unnecessary unless you do not want to use a transpiler/bundler or use the default port of `5241`. Also, note that all of the templates other than the `javascript` template are pre-configured to use webpack by default and the `--use webpack` is automatically added when you run the `build` and `start` commands. Take a look at the `scripts` property in the `package.json` of those templates and you will see the following: + +```json +"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. +
+ +| Template | Framework | +| ---------------- | ---------------- | +| `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](../../references/document-sandbox/): + +| Template | Description | +| ---------------- | ---------------- | +| `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: + +```bash +npx @adobe/create-ccweb-add-on --template