New VS Code Debugging Tools for Alexa

During the last months, the Alexa team has launched a bunch of useful tools for Visual Studio Code. The purpose of these new features is to have a single place with everything set up. Also having all these tools in the same place, we do not have to switch between multiple apps or tabs. In this article, I will show you how you can have a full dev-env for Alexa skills on Visual Studio Code.

• New VS Code Debugging Tools for Alexa
  • Prerequisites
  • Setting up our Alexa Skill
  • Creating the Visual Studio Configuration
  • Alexa Simulator
  • Launching and debugging our Alexa Skill locally
  • Video with the full explanation
  • Resources
  • Conclusion

Prerequisites

Here are the technologies used in this project:

• Node.js v14.x
• Visual Studio Code
• Alexa extension on VS Code

Setting Up Our Alexa Skill

The first step we need to do to enable local debugging on our Visual Studio Code is basically just adding 2 packages npm: ask-sdk-model and ask-sdk-local-debug. The first one you should already have, but it is worth it to upgrade it to the latest version. You should use v1.29.0 or higher!

The second package, ask-sdk-local-debug, is the most important one. This is a devDependency instead of a normal dependency. Why? Well, we just need it only for development purposes. This package is the one that we are going to use to launch our AWS Lambda locally and intercept all the calls from the Alexa Voice Service.

To install these dependencies, you have to run these commands:

1. For npm:

    npm install --save ask-sdk-model@^1.29.0
    npm install --save-dev ask-sdk-local-debug

2. For yarn:

    yarn add ask-sdk-model@^1.29.0
    yarn add ask-sdk-local-debug --dev

With these packages installed/updated, we have done great progress on this journey! Let's continue with the following steps.

Creating the Visual Studio Configuration

Once we have the packages we need installed/upgraded, we need to create a Visual Studio configuration to launch our AWS Lambda.

All the Visual Studio configurations should be placed down in the .vscode folder. In this folder, we are going to create a file called launch.json:

    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Debug Alexa Skill (Node.js)",
                "type": "node",
                "request": "launch",
                "program": "${command:ask.debugAdapterPath}",
                "args": [
                    "--accessToken",
                    "${command:ask.accessToken}",
                    "--skillId",
                    "${command:ask.skillIdFromWorkspace}",
                    "--handlerName",
                    "handler",
                    "--skillEntryFile",
                    "${workspaceFolder}/lambda/index.js",
                    "--region",
                    "EU"
                ]
            }
        ]
    }

Let's explain a little bit deeper the most relevant parameters that we have in this configuration that we called Debug Alexa Skill (Node.js):

1. program: this parameter auto-detects the launcher program that we need to run our AWS Lambda locally. This program was installed when we installed the ask-sdk-local-debug package.
2. arguments:
   1. accessToken: this is the token we need to intercept the Alexa skill invocations locally.
   2. skillId: this is the id of our Alexa skill.
   3. handlerName: this is the name of the object created on our AWS Lambda that will get all the invocations. 
   4. skillEntryFile: where the handler is located (in which file).
   5. region; the region of YOUR Alexa developer account. I set to EU because my account is from Europe. The available values are NA (North America), FE (Far East), EU (Europe).

Creating this configuration you will be able to run your AWS directly on your VS Code from the debug tab:

And you will see this output on your Debug Console:

After this, you can set up all the breakpoints you want.

Alexa Simulator

When you install the Alexa extension on your VS Code you will see the Alexa icon on the left sidebar. Clicking there you will see a lot of options that you can use for your daily development like downloading the interaction model, the APL viewer, downloading the skill manifest, deploying your Alexa skill, or directly testing your skill within VS Code:

If we click on the Simulator, we will have a screen very similar to the test tab on the Alexa Developer Console but now on your IDE!

Having these nice tools properly set, it's time to launch our Alexa skill and see if the code stops on the breakpoints.

Launching and Debugging Our Alexa Skill Locally

When we invocate the Alexa skill from the Simulator and you have run your AWS Lambda locally, you will start seeing that all the interactions are intercepting:

So this means that the code that is executing is the code that we have on our lambda folder locally! Let's put some breakpoints and see if that works:

And voilà, it worked!

Video With the Full Explanation

And that's it, here you have the full explanation in an Alexa Office EU Hours session with me and Gaetano Ursomano from the Alexa team.

Resources

• Official Alexa Skills Kit Node.js SDK — The Official Node.js SDK Documentation
• Official Alexa Skills Kit Documentation — Official Alexa Skills Kit Documentation

Conclusion

As you can see, the Amazon team has created nice tools to have everything in the same ecosystem. Looking forward to seeing what you are going to develop!

I hope this example project is useful to you. You can find the code here.

That's all folks! Happy coding!