App Builder Configuration Files

Overview#

An app has three configuration files, defined in the root of the project folder:

• app.config.yaml is the main configuration file, defining the application's behavior and implementation.
• .env is used to store secrets and environment variables available during build time.
• .aio is populated by the aio CLI to store the current Developer Console Workspace details.

Note: .env and .aio files should not be committed to version control.

app.config.yaml#

Tl;dr: give me a full example:#

# standalone application config
application:
  hostname: 'customhost'
  runtimeManifest:
    packages:
      application-pkg:
        actions:
          count-apples:
            function: actions/count-apples/index.js
            web: 'yes'
            annotations:
              require-adobe-auth: true
  hooks:
    post-app-build: 'echo hook'

# extension points config
extensions:
  dx/excshell/1:
    # $include directive stores config in a separate file
    $include: ./dx-excshell-1/ext.config.yaml
  dx/asset-compute/worker/1:
    operations:
      workerProcess:
        - type: action
          impl: dx-asset-compute-worker-1/myworker
    runtimeManifest:
      packages:
        dx-asset-compute-worker-1:
          actions:
            myworker:
              function: actions/worker/index.js
              web: 'yes'
CopyCopied to your clipboard
1# standalone application config
2application:
3  hostname: 'customhost'
4  runtimeManifest:
5    packages:
6      application-pkg:
7        actions:
8          count-apples:
9            function: actions/count-apples/index.js
10            web: 'yes'
11            annotations:
12              require-adobe-auth: true
13  hooks:
14    post-app-build: 'echo hook'
15
16# extension points config
17extensions:
18  dx/excshell/1:
19    # $include directive stores config in a separate file
20    $include: ./dx-excshell-1/ext.config.yaml
21  dx/asset-compute/worker/1:
22    operations:
23      workerProcess:
24        - type: action
25          impl: dx-asset-compute-worker-1/myworker
26    runtimeManifest:
27      packages:
28        dx-asset-compute-worker-1:
29          actions:
30            myworker:
31              function: actions/worker/index.js
32              web: 'yes'

Standalone application and extensions#

The app.config.yaml file can contain two top level fields: application and extensions. Only one is required.

# app.config.yaml

application:
  <common-config>
extensions:
  <extension-type>:
    <extension-definition>
    <common-config>
CopyCopied to your clipboard
1# app.config.yaml
2
3application:
4  <common-config>
5extensions:
6  <extension-type>:
7    <extension-definition>
8    <common-config>

A project can implement a standalone application and N extensions.

Common configuration#

Extensions and the standalone application behave in a similar way. Both can contain a UI and actions and both support a common configuration. The common configuration contains following fields:

# <common-config>

runtimeManifest:
  <runtime-manifest>
hooks:
  <app-hooks>
actions: <path to action folder>
web-src: <path to web folder>
unitTest: <path to unit test folder>
e2eTest: <path to e2e test folder>
dist: <path to build folder>
htmlCacheDuration: <cache duration for UI html files, default: 60s>
jsCacheDuration: <cache duration for UI JS files, default: about a week>
cssCacheDuration: <cache duration for UI JS files, default: about a week>
imageCacheDuration: <cache duration for UI JS files, default: about a week>
tvmurl: <alternative tvm url used to upload the UI>
awsaccesskeyid: <upload UI to own s3, provide credentials>
awssecretaccesskey: <upload UI to own s3, provide credentials>
s3bucket: <upload UI to own s3, provide credentials>
hostname: <alternative hostname for the UI>
CopyCopied to your clipboard
1# <common-config>
2
3runtimeManifest:
4  <runtime-manifest>
5hooks:
6  <app-hooks>
7actions: <path to action folder>
8web-src: <path to web folder>
9unitTest: <path to unit test folder>
10e2eTest: <path to e2e test folder>
11dist: <path to build folder>
12htmlCacheDuration: <cache duration for UI html files, default: 60s>
13jsCacheDuration: <cache duration for UI JS files, default: about a week>
14cssCacheDuration: <cache duration for UI JS files, default: about a week>
15imageCacheDuration: <cache duration for UI JS files, default: about a week>
16tvmurl: <alternative tvm url used to upload the UI>
17awsaccesskeyid: <upload UI to own s3, provide credentials>
18awssecretaccesskey: <upload UI to own s3, provide credentials>
19s3bucket: <upload UI to own s3, provide credentials>
20hostname: <alternative hostname for the UI>

Runtime Manifest#

The runtimeManifest field holds the backend configuration deployed into Adobe I/O Runtime. The full spec can be found here Here is an example to get started:

runtimeManifest
   packages:
     myapp:
       license: Apache-2.0
       actions:
         generic:
           # path relative to the configuration file
           function: src/myapp/actions/generic/index.js
           web: 'yes'
           annotations:
            require-adobe-auth: true
         target:
           function: src/myapp/actions/target/index.js
           web: 'yes'
           limits:
             timeout: 60
             memory: 512
CopyCopied to your clipboard
1runtimeManifest
2   packages:
3     myapp:
4       license: Apache-2.0
5       actions:
6         generic:
7           # path relative to the configuration file
8           function: src/myapp/actions/generic/index.js
9           web: 'yes'
10           annotations:
11            require-adobe-auth: true
12         target:
13           function: src/myapp/actions/target/index.js
14           web: 'yes'
15           limits:
16             timeout: 60
17             memory: 512

Hooks to customize the tooling#

Hooks can be used to customize aio app commands. Hooks are documented here.

Extension specific configuration#

Extension types#

The <extension-type> indicates which product the extension is extending, currently we support the following product extensions:

1. dx/excshell/1 to implement an Experience Cloud Shell single page application.
2. dx/asset-compute/worker/1 to implement an AEM Asset Compute worker.

dx/excshell/1 definition#

The Experience Cloud Shell extension supports a view operation that points to the entry html file of the SPA. In the following example the impl field points to an index.html file stored in the web/ folder of the extension.

extensions
  dx/excshell/1:
    operations:
      view:
        - type: web
          impl: index.html
     web-src: web/
CopyCopied to your clipboard
1extensions
2  dx/excshell/1:
3    operations:
4      view:
5        - type: web
6          impl: index.html
7     web-src: web/

dx/asset-compute/worker/1 definition#

The AEM Asset Compute worker extension supports a workerProcess operation that points to the backend Adobe I/O Runtime action implementing the worker logic. In the following example the impl field points to the dx-asset-compute-worker-1/worker action defined in the runtimeManifest.

extensions
  dx/asset-compute/worker/1:
    operations:
      workerProcess:
        - type: action
          impl: dx-asset-compute-worker-1/myworker
    runtimeManifest:
      packages:
        dx-asset-compute-worker-1:
          actions:
            myworker:
              function: actions/worker/index.js
              web: 'yes'
CopyCopied to your clipboard
1extensions
2  dx/asset-compute/worker/1:
3    operations:
4      workerProcess:
5        - type: action
6          impl: dx-asset-compute-worker-1/myworker
7    runtimeManifest:
8      packages:
9        dx-asset-compute-worker-1:
10          actions:
11            myworker:
12              function: actions/worker/index.js
13              web: 'yes'

The $include directive#

The $include directive allows to defer any part of the app.config.yaml to another file. In the following example, the dx/excshell/1 configuration is stored in another ./src/dx-excshell-1/ext.config.yaml file.

extensions:
  dx/excshell/1:
    $include: ./src/dx-excshell-1/ext.config.yaml
CopyCopied to your clipboard
1extensions:
2  dx/excshell/1:
3    $include: ./src/dx-excshell-1/ext.config.yaml

Configuration paths defined in ./src/dx-excshell-1/ext.config.yaml must be relative to that file.

.env#

The .env file is used to store:

1. secrets to be injected into I/O Runtime Actions.
2. environment variables available to hooks.
3. auto generated secrets used by the aio CLI, prefixed by AIO_, those should not be edited.

.aio#

The .aio file is auto generated and contains Developer Console specific configuration. This file is updated via the aio app use command and should not be edited manually.

Legacy configuration system#

Apps initialized using a @adobe/aio-cli CLI version prior to 8.x use a legacy configuration system that we still support in newer CLI versions. Those apps do not support extensions, and only get deployed as standalone applications.

The legacy configuration system does not have an app.config.yaml and instead uses:

1. .aio to store common configuration bits, but hooks and Runtime Manifest, such as actions path.
2. manifest.yaml to stores the Runtime Manifest.
3. package.json to store hooks.
4. .env behaves the same.

Last updated 10/26/2021

Was this helpful?

Yes

No