@alexa/acdl

Alexa Conversations Description Language (ACDL) Compiler

This package contains the ACDL compiler API.

Resources

• ACDL Reference Documentation

Installation

npm i @alexa/acdl

CLI

We recommend that you use the askx CLI to work with the compiler, but @alexa/acdl also contains its own CLI, acc, with utilities specific to ACDL.

Usage: acc

Commands:
  acc compile                        compile ACDL module
  acc package                        create a skill-package
  acc decompile                      decompile ASKIR files to ACDL files and
                                     move the ASKIR files to the build directory
  acc deploy                         package and deploy the skill
  acc bootstrap-lwa-secrets-manager  store LWA refresh token credentials in a
                                     secure AWS Secret managed by AWS Secrets
                                     Manager
  acc bootstrap                      Creates a CloudFormation stack with a
                                     Secure AWS Secret Manager and uploads your
                                     LWA credentials credential to the Secret.

Options:
      --version          Show version number                           [boolean]
  -v, --verbose          Run with verbose logging     [boolean] [default: false]
      --skip-validation  Force the CLI to generate ASKIR without validation.
                                                      [boolean] [default: false]
  -h, --help             Show help                                     [boolean]

Project API

@alexa/acdl is a TypeScript/JavaScript library that exposes APIs for reading, analyzing and writing ACDL and ASKIR Module Files.

Below are some top-level APIs for loading, validating and compiling an ACDL Project:

import * as acdl from "@alexa/acdl";

const project = await acdl.loadProject(await acdl.loadProjectConfig("./my-project-path"));

// validate the correctness
const errors = acdl.validateProject(project);

const compiledProject = acdl.compileProject(project);

// synthesize ACDL files to ASKIR modules and write them to the outDir
await acdl.synthesizeProject(project);

await acdl.bundleProject(project);

Project Configuration

Note the await acdl.loadProjectConfig("./my-project-path");. The compiler will attempt to load configuration from the ask field in package.json or from an ask.json file at the root of the ./my-project-path.

For example:

{
  "srcDir": "src",
  "outDir": "build"
}

This configuration instructs the compiler to load ACDL and ASKIR JSON Module files from the src/ folder and write all compiled files to build/.

src/
  -my-dialog.acdl ## file authored by the developer
build/
  -my-dialog.json ## file written by the compiler when running

Skill Package Bundle

The output of bundleProject is a valid Skill Package that can be deployed to SMAPI.

To bundle a Skill Package, you must specify the fully qualified name of your Skill in your ASK configuration:

{
  "srcDir": "src",
  "outDir": "build",
  "skill": "org.example.MySkill"
}

A skill-package folder will then be included in the outDir:

build/
  skill-package/
    conversations/
      -my-dialog.json
    response/prompts/
      template/
        -document.json
    interactionModels/custom/
      -en-US.json