Development

Localhost dev server

The aio-cli includes a development server for seamless local development, so you can run, develop, and test your applications on localhost. Traffic is securely served over HTTPS using a self-signed certificate. The server supports hot reloading, so you can instantly see the effects of any changes made to your application.

Note: as is common with self-signed certificates, you may need to accept 'unsafe site' warnings explicitly, and manually trust the certificate in your browser settings.

`aio app dev` vs. `aio app run`

These commands are very similar, but their differences give you different ways of working with your application. Both commands:

Allow browser debugging and run a local webserver to serve your front end on localhost
Support browser hot reload on front-end code changes

When you use the command aio app run, the following events occur before the localhost webserver is started:

Action code is transpiled, zipped, and deployed to Runtime
Web action urls are written to /src/dx-excshell-1/web-src/src/config.json
Front-end code is built and served on localhost
Web action calls from your front-end are directed to Runtime
Polling: action logs are output in the terminal
Hot reload: changes to action code are re-built and re-deployed
Activation records are kept, and may be queried for outputs, timing, logs, etc.
Logs may be forwarded

When you use the command aio app dev:

Web action urls are written to /src/dx-excshell-1/web-src/src/config.json in the form https://localhost:PORT/api/v1/web/<package-name>/<action-name>
Front-end code is built and served on localhost
Action calls from your front end are run in a debuggable local node process
Action logs are output immediately to the terminal
Changes to action code are loaded on the next call to the action; modules are not cached
There are no activation records
Logs cannot be forwarded

State-lib and Files-lib usage

There are also differences in what your actions can do in these cases. The storage libraries have security restrictions that limit calls from outside Runtime actions, so if your action needs either state or files libs, it will fail with aio app dev. Third-party APIs may have similar restrictions.

Debugging

This section covers how to debug your App Builder application front-end and back-end code with full source maps support using VS Code Debugging or Chrome DevTools.

Note: although any debugger that can attach to Node.js can technically be used to debug App Builder applications, some of the details will differ from the configurations covered here. For details on node debugging see the Node.js Debugging Guide

Debugging with VS code

Create a file named .vscode/launch.json at the root of your project with this content:

{
  "version": "0.3.0",
  "configurations": [
    {
      "name": "App Builder: debug actions",
      "type": "node-terminal",
      "request": "launch",
      "command": "aio app dev",
      "skipFiles": [
        "<node_internals>/**/*.js",
        "${workspaceFolder}/node_modules/**/*.js"
      ]
    }, {
      "name": "App Builder: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "aio app dev",
      "sourceMapPathOverrides": {
        "/__parcel_source_root/*": "${webRoot}/*"
      },
      "skipFiles": [
        "<node_internals>/**/*.js",
        "${workspaceFolder}/node_modules/**/*.js"
      ],
      "serverReadyAction": {
        "pattern": "server running on port : ([0-9]+)",
        "uriFormat": "https://localhost:%s",
        "action": "debugWithChrome",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}
Copied to your clipboard
{
  "version": "0.3.0",
  "configurations": [
    {
      "name": "App Builder: debug actions",
      "type": "node-terminal",
      "request": "launch",
      "command": "aio app dev",
      "skipFiles": [
        "<node_internals>/**/*.js",
        "${workspaceFolder}/node_modules/**/*.js"
      ]
    }, {
      "name": "App Builder: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "aio app dev",
      "sourceMapPathOverrides": {
        "/__parcel_source_root/*": "${webRoot}/*"
      },
      "skipFiles": [
        "<node_internals>/**/*.js",
        "${workspaceFolder}/node_modules/**/*.js"
      ],
      "serverReadyAction": {
        "pattern": "server running on port : ([0-9]+)",
        "uriFormat": "https://localhost:%s",
        "action": "debugWithChrome",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Open the Debug panel (Ctrl+Shift+D on Windows/Linux; ⇧+⌘+D on MacOS)

Note: The debug configuration is dynamic and allows you to set a port in the .env file, for example PORT=3000

Actions are loaded dynamically, so the code is not evaluated until an http request is made. This means breakpoints in your action code will be grayed out until you trigger a call to the action. Web action urls are mapped to https://localhost:PORT/api/v1/web/<package-name>/<action-name> and can be called from your front end, opening the url in your browser, with cURL, etc.

You can use the step-through debugging features of VS Code, inspect variables, add watches, etc.

Secure actions

The aio app dev command simulates Adobe authentication (i.e. require-adobe-auth annotation). If your actions are secured with require-adobe-auth: true, you will have to include both Authorization and x-gw-ims-org-id headers in your requests. Any value will work.