{"id":15619230,"url":"https://github.com/xavidop/alexa-typescript-lambda-helloworld","last_synced_at":"2026-03-05T16:41:13.911Z","repository":{"id":44757408,"uuid":"253567072","full_name":"xavidop/alexa-typescript-lambda-helloworld","owner":"xavidop","description":"Alexa Skill template using TypeScript","archived":false,"fork":false,"pushed_at":"2022-01-26T15:18:20.000Z","size":378,"stargazers_count":17,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-28T17:17:43.672Z","etag":null,"topics":["alexa","alexa-custom-skill","alexa-sdk","alexa-skill","npm","skill-sample","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xavidop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"xavidop","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-04-06T17:19:21.000Z","updated_at":"2024-03-24T04:20:47.000Z","dependencies_parsed_at":"2022-09-13T15:31:09.169Z","dependency_job_id":null,"html_url":"https://github.com/xavidop/alexa-typescript-lambda-helloworld","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Falexa-typescript-lambda-helloworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Falexa-typescript-lambda-helloworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Falexa-typescript-lambda-helloworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Falexa-typescript-lambda-helloworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xavidop","download_url":"https://codeload.github.com/xavidop/alexa-typescript-lambda-helloworld/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251352639,"owners_count":21575865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","alexa-custom-skill","alexa-sdk","alexa-skill","npm","skill-sample","typescript"],"created_at":"2024-10-03T08:03:49.001Z","updated_at":"2026-03-05T16:41:13.869Z","avatar_url":"https://github.com/xavidop.png","language":"TypeScript","readme":"# Alexa Skill with TypeScript\n\nAlexa skills can be developed using Alexa Lambda functions or a REST API endpoint. \nLambda function is Amazon's implementation of serverless functions available in AWS. \nAmazon recommends using Lambda functions despite they are not easy to debug. \nWhile you can log to a CloudWatch log, you can't hit a breakpoint and step into the code. \n \nThis makes live debugging of Alexa requests a very hard task.\nIn this post, we will implement a custom skill for Amazon Alexa by using TypeScript, npm and AWS Lambda Functions. This skill is basically a Hello World example. \nWith this post you will be able to create a custom skill for Amazon Alexa, implement functionality by using TypeScript and start your custom skill both from your local computer and from AWS.\nThis post contains materials from different resources that can be seen on Resources section.\n\n## Prerequisites\n\nHere you have the technologies used in this project\n1. Amazon Developer Account - [How to get it](http://developer.amazon.com/)\n2. AWS Account - [Sign up here for free](https://aws.amazon.com/)\n3. ASK CLI - [Install and configure ASK CLI](https://developer.amazon.com/es-ES/docs/alexa/smapi/quick-start-alexa-skills-kit-command-line-interface.html)\n4. Node.js v10.x\n5. TypeScript (Version \u003e3.0.0)\n6. Visual Studio Code\n7. npm Package Manager\n8. Alexa ASK for Node.js (Version \u003e2.7.0)\n9. ngrok\n\nThe Alexa Skills Kit Command Line Interface (ASK CLI) is a tool for you to manage your Alexa skills and related resources, such as AWS Lambda functions.\nWith ASK CLI, you have access to the Skill Management API, which allows you to manage Alexa skills programmatically from the command line.\nWe will use this powerful tool to create, build, deploy and manage our Hello World Skill but now, with TypeScript. Let's start!\n\n## Creating the Skill with ASK CLI\n\nIf you want how to create your Skill with the ASK CLI, please follow the first step explained in my [Node.js Skill](https://github.com/xavidop/alexa-nodejs-lambda-helloworld) sample\n\nOnce we have created the Skill in Node.js, we have to rewrite or 'transpile' our code to TypeScript. I have made that work for you. Let's take a look on it!\n\n## Project Files \n\nThese are the main files of the project:\n\n```bash\n\n    ├───.ask/\n    │       config\n    ├───.vscode/\n    │       launch.json\n    ├───hooks/\n    ├───lambda/\n    │   └───custom/\n    │       │   └───build/\n    │       │   local-debugger.js\n    │       │   package.json\n    │       │   tsconfig.json\n    │       │   tslint.json\n    │       └───src/\n    │           ├───index.ts\n    │           ├───errors/\n    │           ├───intents/\n    │           ├───interceptors/\n    │           └───utilities/\n    │\n    ├───models/\n    └───skill.json\n\n```\n\n* .ask: folder which contains the ASK CLI's config file. This config files will remain empty until we execute the command `ask deploy`\n* `.vscode/launch.json`: Launch preferences to run locally your Skill for local testing. This setting launch `lambda/custom/src/local-debugger.js`. This script runs a server on http://localhost:3001 for debug the Skill. It is not traspilled to TypeScript because it is not a part from our lambda. It is a local tool.\n* hooks: A folder that contains the hook scripts. Amazon provides two hooks, post_new_hook and pre_deploy_hook\n  * `post_new_hook`: executed after the Skill creation. Inn Node.js runs `npm install` in each sourceDir in `skill.json`\n  * `pre_deploy_hook`: executed before the Skill deployment. In Node.js runs `npm install` in each sourceDir in `skill.json` as well\n* lambda/custom/src: A folder that contains the source code for the skill's AWS Lambda function:\n  * `index.ts`: the lambda main entry point\n  * `package.json`: this file is core to the Node.js ecosystem and is a basic part of understanding and working with Node.js, npm, and even modern TypeScript\n  * `tsconfig.json`: configuration file that we are going to use for compiling our TypeScript code\n  * `tslint.json`: configuration file used by `gts` (Google TypeScript Style) to check the style of our TypeScript code\n  * `local-debugger.js`: used for debug our skill locally\n  * `errors`: folder that contains all error handlers\n  * `intents`: this one contains all the intent handlers\n  * `interceptors`: interceptors' folder with the i18n initialization\n  * `utilities`: this folder contains the i18n strings, helper functions, constants and TypeScript interfaces\n  * `build`: the output folder after compiling the TypeScript code\n* models – A folder that contains interaction models for the skill. Each interaction model is defined in a JSON file named according to the locale. For example, es-ES.json\n* `skill.json` – The skill manifest. One of the most important files in our project\n\n\n## Lambda function in TypeScript\n\nThe ASK SDK for Node.js makes it easier for you to build highly engaging skills by allowing you to spend more time implementing features and less time writing boilerplate code. \n\nWe are going to use this SDK but now in TypeScript!\n\nYou can find documentation, samples and helpful links in their official [GitHub repository](https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs)\n\nThe main TypeScript file in our lambda project is `index.ts` located in `lambda/custom/src` folder. This file contains all handlers, interceptors and exports the Skill handler in `exports.handler`.\n\nThe `exports.handler` function is executed every time AWS Lambda is initiated for this particular function. \nIn theory, an AWS Lambda function is just a single function. This means that we need to define dispatching logic so a single function request can route to appropriate code, hence the handlers.\n\n```typescript\n  import * as Alexa from 'ask-sdk-core';\n  import { Launch } from './intents/Launch';\n  import { Help } from './intents/Help';\n  import { Stop } from './intents/Stop';\n  import { Reflector } from './intents/Reflector';\n  import { Fallback } from './intents/Fallback';\n  import { HelloWorld } from './intents/HelloWorld';\n  import { ErrorProcessor } from './errors/ErrorProcessor';\n  import { SessionEnded } from './intents/SessionEnded';\n  import { LocalizationRequestInterceptor } from './interceptors/LocalizationRequestInterceptor';\n\n  export const handler = Alexa.SkillBuilders.custom()\n    .addRequestHandlers(\n      // Default intents\n      Launch,\n      HelloWorld,\n      Help,\n      Stop,\n      SessionEnded,\n      Reflector,\n      Fallback\n    )\n    .addErrorHandlers(ErrorProcessor)\n    .addRequestInterceptors(LocalizationRequestInterceptor)\n    .lambda();\n\n```\n\nIt is important to take a look into the `Launch.ts`, imported as `Launch` above, which is the `LaunchRequestHandler` handler located in the `intents` folder as an example of Alexa Skill handler written in TypeScript:\n\n```typescript\n\n  import { RequestHandler, HandlerInput } from 'ask-sdk-core';\n  import { RequestTypes, Strings } from '../utilities/constants';\n  import { IsType } from '../utilities/helpers';\n  import i18n from 'i18next';\n\n  export const Launch: RequestHandler = {\n    canHandle(handlerInput: HandlerInput) {\n      return IsType(handlerInput, RequestTypes.Launch);\n    },\n    handle(handlerInput: HandlerInput) {\n      const speechText = i18n.t(Strings.WELCOME_MSG);\n\n      return handlerInput.responseBuilder\n        .speak(speechText)\n        .reprompt(speechText)\n        .withSimpleCard(i18n.t(Strings.SKILL_NAME), speechText)\n        .getResponse();\n    },\n  };\n\n```\n\n## Building the Skill with Visual Studio Code\n\nInside `package.json`, we will almost always find metadata specific to the project. \nThis metadata helps identify the project and acts as a baseline for users and contributors to get information about the project.\n\nHere is how this file looks like:\n\n```json\n\n  {\n    \"name\": \"alexa-typescript-lambda-helloworld\",\n    \"version\": \"1.0.0\",\n    \"description\": \"Alexa HelloWorld example with TypeScript\",\n    \"main\": \"index.js\",\n    \"scripts\": {\n      \"clean\": \"rimraf build\",\n      \"compile\": \"tsc --build tsconfig.json --pretty\",\n      \"build-final\": \"cpy package.json build \u0026\u0026 cd build/ \u0026\u0026 npm install --production\",\n      \"test\": \"echo \\\"No test specified yet\\\" \u0026\u0026 exit 0\",\n      \"lint-check\": \"gts check\",\n      \"lint-clean\": \"gts clean\",\n      \"lint-fix\": \"gts fix\",\n      \"build\": \"npm run clean \u0026\u0026 npm run test \u0026\u0026 npm run lint-check \u0026\u0026 npm run compile \u0026\u0026 npm run build-final\"\n    },\n    \"repository\": {\n      \"type\": \"git\",\n      \"url\": \"https://github.com/xavidop/alexa-typescript-lambda-helloworld.git\"\n    },\n    \"author\": \"Xavier Portilla Edo\",\n    \"license\": \"Apache-2.0\",\n    \"dependencies\": {\n      \"ask-sdk-core\": \"^2.7.0\",\n      \"ask-sdk-model\": \"^1.19.0\",\n      \"aws-sdk\": \"^2.326.0\",\n      \"i18next\": \"^15.0.5\",\n      \"i18next-sprintf-postprocessor\": \"^0.2.2\"\n    },\n    \"devDependencies\": {\n      \"@types/node\": \"^10.10.0\",\n      \"@types/i18next-sprintf-postprocessor\": \"^0.2.0\",\n      \"typescript\": \"^3.0.2\",\n      \"cpy-cli\": \"^3.1.0\",\n      \"rimraf\": \"^3.0.0\",\n      \"ts-node\": \"^7.0.1\",\n      \"gts\": \"^1.1.2\"\n    }\n  }\n\n\n```\n\nWith TypeScript we have to compile our code to generate the JavaScript code. For build our Skill, we can run the following command:\n\n```bash\n\n  npm run build\n\n```\nThis command will execute these actions:\n1. Remove the `build` folder located in `lambda/custom` with the command `rimraf build`. This folder contains the output of compiling the TypeScript code\n2. Check the style of our TypeScript code with the command `gts check` using the file `tslint.json`\n3. Compiles the TypeScript and generates the JavaScript code in the output folder `lambda/custom/build` using the command `tsc --build tsconfig.json --pretty`\n4. Copy the `package.json` to the `build` folder because is needed to generate the final lambda code\n5. Finally, it will run the `npm install --production` in `build` folder to get the final lambda code that we are going to upload to AWS with the ASK CLI.\n\nAs you can see, this process in a TypeScript environment is more complex than in JavaScript one.\n\n## Running the Skill with Visual Studio Code\n\nThe `launch.json` file in `.vscode` folder has the configuration for Visual Studio Code which allow us to run our lambda locally:\n\n```json\n\n  {\n      \"version\": \"0.2.0\",\n      \"configurations\": [\n          {\n              \"type\": \"node\",\n              \"request\": \"launch\",\n              \"name\": \"Launch Skill\",\n              // Specify path to the downloaded local adapter(for nodejs) file\n              \"program\": \"${workspaceRoot}/lambda/custom/local-debugger.js\",\n              \"args\": [\n                  // port number on your local host where the alexa requests will be routed to\n                  \"--portNumber\", \"3001\",\n                  // name of your nodejs main skill file\n                  \"--skillEntryFile\", \"${workspaceRoot}/lambda/custom/build/index.js\",\n                  // name of your lambda handler\n                  \"--lambdaHandler\", \"handler\"\n              ]\n          }\n      ]\n  }\n\n```\nThis configuration file will execute the following command:\n\n```bash\n\n  node --inspect-brk=28448 lambda\\custom\\local-debugger.js --portNumber 3001 --skillEntryFile lambda/custom/build/index.js --lambdaHandler handler\n\n```\n\nThis configuration uses the `local-debugger.js` file which runs a [TCP server](https://nodejs.org/api/net.html) listening on http://localhost:3001\n\nFor a new incoming skill request a new socket connection is established.\nFrom the data received on the socket the request body is extracted, parsed into JSON and passed to the skill invoker's lambda handler.\nThe response from the lambda handler is parsed as a HTTP 200 message format as specified [here](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#http-header-1)\nThe response is written onto the socket connection and returned.\n\nAfter configuring our launch.json file and understanding how the local debugger works, it is time to click on the play button:\n\n![image](img/run.png)\n\nAfter executing it, you can send Alexa POST requests to http://localhost:3001.\n\n## Debugging the Skill with Visual Studio Code\n\nFollowing the steps before, now you can set up breakpoints wherever you want inside all TypeScript files in order to debug your skill:\n\n![image](img/debug.png)\n\n## Testing requests locally\n\nI'm sure you already know the famous tool call [Postman](https://www.postman.com/). REST APIs have become the new standard in providing a public and secure interface for your service. Though REST has become ubiquitous, it's not always easy to test. Postman, makes it easier to test and manage HTTP REST APIs. Postman gives us multiple features to import, test and share APIs, which will help you and your team be more productive in the long run.\n\nAfter run your application you will have an endpoint available at http://localhost:3001. With Postman you can emulate any Alexa Request. \n\nFor example, you can test a `LaunchRequest`:\n\n```json\n\n  {\n    \"version\": \"1.0\",\n    \"session\": {\n      \"new\": true,\n      \"sessionId\": \"amzn1.echo-api.session.[unique-value-here]\",\n      \"application\": {\n        \"applicationId\": \"amzn1.ask.skill.[unique-value-here]\"\n      },\n      \"user\": {\n        \"userId\": \"amzn1.ask.account.[unique-value-here]\"\n      },\n      \"attributes\": {}\n    },\n    \"context\": {\n      \"AudioPlayer\": {\n        \"playerActivity\": \"IDLE\"\n      },\n      \"System\": {\n        \"application\": {\n          \"applicationId\": \"amzn1.ask.skill.[unique-value-here]\"\n        },\n        \"user\": {\n          \"userId\": \"amzn1.ask.account.[unique-value-here]\"\n        },\n        \"device\": {\n          \"supportedInterfaces\": {\n            \"AudioPlayer\": {}\n          }\n        }\n      }\n    },\n    \"request\": {\n      \"type\": \"LaunchRequest\",\n      \"requestId\": \"amzn1.echo-api.request.[unique-value-here]\",\n      \"timestamp\": \"2020-03-22T17:24:44Z\",\n      \"locale\": \"en-US\"\n    }\n  }\n\n```\n\n## Deploying your Alexa Skill\n\nWith the code ready to go, we need to deploy it on AWS Lambda so it can be connected to Alexa.\n\nBefore deploy the Alexa Skill, we can show the `config` file in `.ask` folder it is empty:\n\n```json\n    {\n      \"deploy_settings\": {\n        \"default\": {\n          \"skill_id\": \"\",\n          \"was_cloned\": false,\n          \"merge\": {}\n        }\n      }\n    }\n\n```\n\nDeploy Alexa Skill with ASK CLI:\n\n```bash\n    ask deploy\n```\n\nAs the official documentation says:\n\nWhen the local skill project has never been deployed, ASK CLI creates a new skill in the development stage for your account, then deploys the skill project. If applicable, ASK CLI creates one or more new AWS Lambda functions in your AWS account and uploads the Lambda function code. Specifically, ASK CLI does the following:\n\n1. Looks in your skill project's config file (in the .ask folder, which is in the skill project folder) for an existing skill ID. If the config file does not contain a skill ID, ASK CLI creates a new skill using the skill manifest in the skill project's skill.json file, then adds the skill ID to the skill project's config file.\n2. Looks in your skill project's manifest (skill.json file) for the skill's published locales. These are listed in the manifest.publishingInformation.locales object. For each locale, ASK CLI looks in the skill project's models folder for a corresponding model file (for example, es-ES.json), then uploads the model to your skill. ASK CLI waits for the uploaded models to build, then adds each model's eTag to the skill project's config file.\n3. Looks in your skill project's manifest (skill.json file) for AWS Lambda endpoints. These are listed in the manifest.apis.\u003cskill type\u003e.endpoint or manifest.apis.\u003cskill type\u003e.regions.\u003cregion code\u003e.endpoint objects (for example, manifest.apis.custom.endpoint or manifest.apis.smartHome.regions.NA.endpoint). Each endpoint object contains a sourceDir value, and optionally a uri value. ASK CLI upload the contents of the sourceDir folder to the corresponding AWS Lambda function and names the Lambda function the same as the uri value. For more details about how ASK CLI performs uploads to Lambda, see AWS Lambda deployment details.\n4. Looks in your skill project folder for in-skill products, and if it finds any, uploads them to your skill. For more information about in-skill products, see the In-Skill Purchasing Overview.\n\n\nAfter the execution of the above command, we will have the `config` file properly filled:\n\n```json\n\n  {\n    \"deploy_settings\": {\n      \"default\": {\n        \"skill_id\": \"amzn1.ask.skill.945814d5-9b30-4ee7-ade6-f5ef017a1c17\",\n        \"was_cloned\": false,\n        \"merge\": {},\n        \"resources\": {\n          \"manifest\": {\n            \"eTag\": \"ea0bd8c176a560f95a64fe7a1ba99315\"\n          },\n          \"interactionModel\": {\n            \"es-ES\": {\n              \"eTag\": \"4a185611054c722446536c5659593aa3\"\n            }\n          },\n          \"lambda\": [\n            {\n              \"alexaUsage\": [\n                \"custom/default\"\n              ],\n              \"arn\": \"arn:aws:lambda:us-east-1:141568529918:function:ask-custom-alexa-typescript-lambda-helloworld-default\",\n              \"awsRegion\": \"us-east-1\",\n              \"codeUri\": \"lambda/custom/build\",\n              \"functionName\": \"ask-custom-alexa-typescript-lambda-helloworld-default\",\n              \"handler\": \"index.handler\",\n              \"revisionId\": \"477bcf34-937d-4fa4-8588-8db8ec1e7213\",\n              \"runtime\": \"nodejs10.x\"\n            }\n          ]\n        }\n      }\n    }\n  }\n\n```\n\n**NOTE:** after rewriting our code to TypeScript we need to change the `codeUri` from `lambda/custom` to `lambda/custom/build` because of our code compiled from TypeScript to JavaScript goes to the output folder `build`.\n\n## Test requests directly from Alexa\n\nngrok is a very cool, lightweight tool that creates a secure tunnel on your local machine along with a public URL you can use for browsing your local site or APIs.\n\nWhen ngrok is running, it listens on the same port that you’re local web server is running on and proxies external requests to your local machine\n\nFrom there, it’s a simple step to get it to listen to your web server. Say you’re running your local web server on port 3001. In terminal, you’d type in: `ngrok http 3001`. This starts ngrok listening on port 3001 and creates the secure tunnel:\n\n![image](img/tunnel.png)\n\nSo now you have to go to [Alexa Developer console](https://developer.amazon.com/alexa/console/ask), go to your skill \u003e endpoints \u003e https, add the https url generated above . Eg: https://20dac120.ngrok.io.\n\nSelect the My development endpoint is a sub-domain.... option from the dropdown and click save endpoint at the top of the page.\n\nGo to Test tab in the Alexa Developer Console and launch your skill.\n\nThe Alexa Developer Console will send a HTTPS request to the ngrok endpoint (https://20dac120.ngrok.io) which will route it to your skill running on Web API server at http://localhost:3001.\n\n\n## Resources\n* [Official Alexa Skills Kit Node.js SDK](https://www.npmjs.com/package/ask-sdk) - The Official Node.js SDK Documentation\n* [Official Alexa Skills Kit Documentation](https://developer.amazon.com/docs/ask-overviews/build-skills-with-the-alexa-skills-kit.html) - Official Alexa Skills Kit Documentation\n\n\n## Conclusion \n\nThis was a basic tutorial to learn Alexa Skills using Node.js and TypeScript.\nAs you have seen in this example, the Alexa Skill Kit for Node.js and the Alexa Tools like ASK CLI can help us a lot and also they give us the possibility to create skills in TypeScript in an easy way. \nI hope this example project is useful to you.\n\nThat's all folks!\n\nHappy coding!\n","funding_links":["https://github.com/sponsors/xavidop"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavidop%2Falexa-typescript-lambda-helloworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxavidop%2Falexa-typescript-lambda-helloworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavidop%2Falexa-typescript-lambda-helloworld/lists"}