Fork of Litexa, rewritten in TypeScript.
Litexa is an Alexa domain specific language, developed for long form multi-turn skills such as games.
Full documentation is available at https://litexa.com.
NOTE: This is a fork of Litexa being refactored to use TypeScript instead of Coffeescript. This is still a work-in-progress.
WARNING: @litexa/assets-wav
has been removed for the time being. Eventually, it will be rewritten using a more up-to-date audio encoder/decoder, but for now, it has been removed.
Disclaimer: Litexa is an Alexa Labs community-supported project (alpha) from the Alexa Games team at Amazon. We (Alexa Games) have used Litexa to develop and ship 20+ Alexa skills. Your feedback is welcome and we are happy to consider contributions. Otherwise, you are free to use and modify this software as needed. As with all open-source packages, please use them in accordance with the licenses assigned to each package. For official Alexa supported skill development tools, we recommend using tools in the Alexa Skills Kit like Skill Flow Builder and the ASK SDK. Thanks and enjoy!
The following packages are in this repo.
The compiler and common tooling for Litexa. Installing this globally installs the Litexa command line tool.
A deployment module that pushes a skill to AWS using the services: Lambda, DynamoDB, and S3. Click to learn more about the Litexa deployment module.
An extension that makes working with APL documents in your Litexa project more powerful with shorthand for managing APL documents and common design patterns. Click to learn more about the APL extension.
VS Code extensions for the Litexa language that provides syntax highlighting for .litexa
files. Click to learn more about the VS Code extension.
While having split code-bases facilitates code-sharing, it comes at a cost of increased difficulty in tracking and testing features across repositories. For this reason we've decided to organize this codebase into a multi-package repository (or monorepo).
This monorepo uses Lerna to manage all of its packages.
To get started, run npm install
from the root directory of the repository. This will install
the dependencies and bootstrap Lerna. Lerna bootstrap
and link
are called during postinstall.
To learn more, check out the
@learna/bootstrap documentation.
During development, you should install any packages you plan on modifying from the local package.
npm install -g ./packages/litexa
You can also install multiple packages at the same time:
npm install -g ./packages/litexa ./packages/litexa-apl ./packages/litexa-deploy-aws
It's important to get your base project to a consistent state. A utility function clean
has been
provided for you. It removes node_modules
and re-installs them for you and the runs
npx lerna clean
which goes through each managed package and removes its node_modules
For more information on Lerna's clean
command, check out the
@learna/clean documentation.
To test your package run
npx lerna run test --scope [package-your-developing]
for example, if you wanted to run test litexa and @litexa/deploy-aws you'd run
npx lerna run test --scope @litexa/core @litexa/deploy-aws
to run all the tests, omit the scoped flag
npx lerna run test
to run test coverage for your package(s) run
npx lerna run coverage --scoped [package-your-testing]
to run them all
npm run coverage:lerna
Integration tests are handled outside of Lerna, by the unpublished @litexa/integration-tests
package
in the ./tests
directory. If you're writing an integration test, add it there. Integration tests can
also be referred to for usage examples of various Litexa features.
Note: all run
does is accept an argument that it's going to use to run the npm script in your
package so all npx lerna run test
is doing is going through each package and running the test
script from your package.json, if the script doesn't exist for a package it skips it.
For more information on the run
command
check out the Lerna docs.
To build the entire project run
npm run build
from the root of the project directory. This command will do the following
- Remove and perform a clean install of the lerna project
- Clean all the package dependencies
- Clean all the test dependencies
- Look at all the packages, find any common dev dependencies or new packages and surface them up as shared dependencies in package.json
- Bootstrap and Hoist them for use with Lerna aka Bundle them
- And run the Coverage for the entire project
if this command succeeds, you should have fair confidence the code is in a good working state.
To add a new package edit the lerna.json
file with your new package run
npm run sync:dependencies
this will run the lerna link
command and bring in the new package as a dependency for the lerna
project, as well as bring up the common devDependencies. After this is done, don't forget to run
npm run clean
to install those dependencies, and version your changes.
For more information on the link
command
check out the lerna docs
Full documentation is available at https://litexa.com. To run the documentation website locally, please do the following.
npm install -g vuepress
npm install -g markdown-it-vuepress-code-snippet-enhanced
In the ./packages/litexa/src/parser/litexa.pegjs
file all the comments can include markdown. From
the root to extract and update the website run
npm run docs:reference
To start the docs website in interactive/watch mode, then run this:
npm run docs:dev
To run both the reference and the interactive site, run.
npm run docs
The website will update with any change in the docs folder. For more info on Vuepress - https://v0.vuepress.vuejs.org/guide/#how-it-works
We are using a small extension to grab code from docs. Info here: https://www.npmjs.com/package/markdown-it-vuepress-code-snippet-enhanced
To build the full static website for S3 or GitHub hosting, run the following:
npm run docs:build
Security is of the utmost importance. This section will describe NPM scripts that can help with making sure that the code base is as secure as possible.
NPM provides a tool that will scan and automatically install any compatible updates
to vulnerable dependencies. More on npm audit
here.
To run the tool against every Litexa package, run the following from the root of the code base:
npm run audit:fix
If the tool does automatically install any compatible updates, it's advised to run
npm run coverage
before you commit any changes (to make sure nothing has broken in
the update).