This project was bootstrapped with Create Alexa App.

Below you will find some information on how to perform common tasks.

You can find the most recent version of this guide here.

Table of Contents

• Updating to New Releases
• Sending Feedback
• Folder Structure
• Available Scripts
  • npm start
  • npm test
  • npm run build
• Supported Language Features and Polyfills
• Syntax Highlighting in the Editor
• Displaying Lint Output in the Editor
• Debugging in the Editor
• Installing a Dependency
• Adding Flow
• Adding Custom Environment Variables
  • Adding Temporary Environment Variables In Your Shell
  • Adding Development Environment Variables In .env
• Running Tests
  • Filename Conventions
  • Command Line Interface
  • Version Control Integration
  • Writing Tests
  • Using Third Party Assertion Libraries
  • Initializing Test Environment
  • Focusing and Excluding Tests
  • Coverage Reporting
  • Continuous Integration
  • Snapshot Testing
  • Editor Integration
• Advanced Configuration
• Troubleshooting
  • npm start doesn’t detect changes
  • npm test hangs on macOS Sierra
  • npm run build silently fails
  • Moment.js locales are missing
• Something Missing?

Updating to New Releases

Create Alexa App is divided into two packages:

• create-alexa-app is a global command-line utility that you use to create new projects.
• alexa-scripts is a development dependency in the generated projects (including this one).

You almost never need to update create-alexa-app itself: it delegates all the setup to alexa-scripts.

When you run create-alexa-app, it always creates the project with the latest version of alexa-scripts so you’ll get all the new features and improvements in newly created apps automatically.

To update an existing project to a new version of alexa-scripts, open the changelog, find the version you’re currently on (check package.json in this folder if you’re not sure), and apply the migration instructions for the newer versions.

In most cases bumping the alexa-scripts version in package.json and running npm install in this folder should be enough, but it’s good to consult the changelog for potential breaking changes.

We commit to keeping the breaking changes minimal so you can upgrade alexa-scripts painlessly.

Sending Feedback

We are always open to your feedback.

Folder Structure

After creation, your project should look like this:

my-app/
  README.md
  node_modules/
  package.json
  src/
    __snapshots__/
      index.test.js.snap
    index.js
    index.test.js

For the project to build, these files must exist with exact filenames:

• src/index.js is the JavaScript entry point.

You can delete or rename the other files.

You may create subdirectories inside src. For faster rebuilds, only files inside src are processed by Webpack.
You need to put any JS files inside src, or Webpack won’t see them.

You can, however, create more top-level directories.
They will not be included in the production build so you can use them for things like documentation.

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.

The console will reload if you make edits.
You will also see any lint errors in the console.

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.
It correctly bundles in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

Supported Language Features and Polyfills

This project supports a superset of the latest JavaScript standard.
In addition to ES6 syntax features, it also supports:

• Exponentiation Operator (ES2016).
• Async/await (ES2017).
• Object Rest/Spread Properties (stage 3 proposal).
• Class Fields and Static Properties (stage 2 proposal).
• SSML JSX
• Flow syntax.

Learn more about different proposal stages.

Note that the project only includes a few ES6 polyfills:

• fetch() via whatwg-fetch.

If you use any other ES6+ features that need runtime support (such as Array.from() or Symbol), make sure you are including the appropriate polyfills manually, or that the browsers you are targeting already support them.

Syntax Highlighting in the Editor

To configure the syntax highlighting in your favorite text editor, head to the relevant Babel documentation page and follow the instructions. Some of the most popular editors are covered.

Displaying Lint Output in the Editor

Some editors, including Sublime Text, Atom, and Visual Studio Code, provide plugins for ESLint.

They are not required for linting. You should see the linter output right in your terminal as well as the browser console. However, if you prefer the lint results to appear right in your editor, there are some extra steps you can do.

You would need to install an ESLint plugin for your editor first. Then, add a file called .eslintrc to the project root:

{
  "extends": "alexa-app"
}

Now your editor should report the linting warnings.

Note that even if you edit your .eslintrc file further, these changes will only affect the editor integration. They won’t affect the terminal and in-browser lint output. This is because Create Alexa App intentionally provides a minimal set of rules that find common mistakes.

If you want to enforce a coding style for your project, consider using Prettier instead of ESLint style rules.

Installing a Dependency

The generated project already includes some dependencies. It also includes a set of scripts used by Create Alexa App as a development dependency. You may install other dependencies with npm:

$ npm install --save <library-name>

Adding Flow

Flow is a static type checker that helps you write code with fewer bugs. Check out this introduction to using static types in JavaScript if you are new to this concept.

Recent versions of Flow work with Create Alexa App projects out of the box.

To add Flow to a Create Alexa App project, follow these steps:

1. Run npm install --save-dev flow-bin (or yarn add --dev flow-bin).
2. Add "flow": "flow" to the scripts section of your package.json.
3. Run npm run flow -- init (or yarn flow -- init) to create a .flowconfig file in the root directory.
4. Add // @flow to any files you want to type check (for example, to src/index.js).

Now you can run npm run flow (or yarn flow) to check the files for type errors.

To learn more about Flow, check out its documentation.

Adding Custom Environment Variables

Your project can consume variables declared in your environment as if they were declared locally in your JS files. By default you will have NODE_ENV defined for you, and any other environment variables starting with ALEXA_APP_.

The environment variables are embedded during the build time.

Note: You must create custom environment variables beginning with ALEXA_APP_. Any other variables except NODE_ENV will be ignored to avoid accidentally exposing a private key on the machine that could have the same name. Changing any environment variables will require you to restart the development server if it is running.

These environment variables will be defined for you on process.env. For example, having an environment variable named ALEXA_APP_SECRET_CODE will be exposed in your JS as process.env.ALEXA_APP_SECRET_CODE.

There is also a special built-in environment variable called NODE_ENV. You can read it from process.env.NODE_ENV. When you run npm start, it is always equal to 'development', when you run npm test it is always equal to 'test', and when you run npm run build to make a production bundle, it is always equal to 'production'. You cannot override NODE_ENV manually. This prevents developers from accidentally deploying a slow development build to production.

These environment variables can be useful for displaying information conditionally based on where the project is deployed or consuming sensitive data that lives outside of version control.

During the build, process.env.ALEXA_APP_SECRET_CODE will be replaced with the current value of the ALEXA_APP_SECRET_CODE environment variable. Remember that the NODE_ENV variable will be set for you automatically.

In order to consume this value, we need to have it defined in the environment. This can be done using two ways: either in your shell or in a .env file. Both of these ways are described in the next few sections.

Having access to the NODE_ENV is also useful for performing actions conditionally:

if (process.env.NODE_ENV !== 'production') {
  analytics.disable();
}

When you compile the app with npm run build, the minification step will strip out this condition, and the resulting bundle will be smaller.

Adding Temporary Environment Variables In Your Shell

Defining environment variables can vary between OSes. It’s also important to know that this manner is temporary for the life of the shell session.

Windows (cmd.exe)

set ALEXA_APP_SECRET_CODE=abcdef&&npm start

(Note: the lack of whitespace is intentional.)

Linux, macOS (Bash)

ALEXA_APP_SECRET_CODE=abcdef npm start

Adding Development Environment Variables In .env

To define permanent environment variables, create a file called .env in the root of your project:

ALEXA_APP_SECRET_CODE=abcdef

.env files should be checked into source control (with the exclusion of .env*.local).

What other .env files are can be used?

• .env: Default.
• .env.local: Local overrides. This file is loaded for all environments except test.
• .env.development, .env.test, .env.production: Environment-specific settings.
• .env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

• npm start: .env.development.local, .env.development, .env.local, .env
• npm run build: .env.production.local, .env.production, .env.local, .env
• npm test: .env.test.local, .env.test, .env (note .env.local is missing)

These variables will act as the defaults if the machine does not explicitly set them.
Please refer to the dotenv documentation for more details.

Note: If you are defining environment variables for development, your CI and/or hosting platform will most likely need these defined as well.

Running Tests

Create Alexa App uses Jest as its test runner.

Jest is a Node-based runner. This means that the tests always run in a Node environment and not in a real browser. This lets us enable fast iteration speed and prevent flakiness.

Filename Conventions

Jest will look for test files with any of the following popular naming conventions:

• Files with .js suffix in __tests__ folders.
• Files with .test.js suffix.
• Files with .spec.js suffix.

The .test.js / .spec.js files (or the __tests__ folders) can be located at any depth under the src top level folder.

We recommend to put the test files (or __tests__ folders) next to the code they are testing so that relative imports appear shorter. For example, if App.test.js and App.js are in the same folder, the test just needs to import App from './App' instead of a long relative path. Colocation also helps find tests more quickly in larger projects.

Command Line Interface

When you run npm test, Jest will launch in the watch mode. Every time you save a file, it will re-run the tests, just like npm start recompiles the code.

The watcher includes an interactive command-line interface with the ability to run all tests, or focus on a search pattern. It is designed this way so that you can keep it open and enjoy fast re-runs. You can learn the commands from the “Watch Usage” note that the watcher prints after every run:

Version Control Integration

By default, when you run npm test, Jest will only run the tests related to files changed since the last commit. This is an optimization designed to make your tests runs fast regardless of how many tests you have. However it assumes that you don’t often commit the code that doesn’t pass the tests.

Jest will always explicitly mention that it only ran tests related to the files changed since the last commit. You can also press a in the watch mode to force Jest to run all tests.

Jest will always run all tests on a continuous integration server or if the project is not inside a Git or Mercurial repository.

Writing Tests

To create tests, add it() (or test()) blocks with the name of the test and its code. You may optionally wrap them in describe() blocks for logical grouping but this is neither required nor recommended.

Jest provides a built-in expect() global function for making assertions. A basic test could look like this:

import sum from './sum';

it('sums numbers', () => {
  expect(sum(1, 2)).toEqual(3);
  expect(sum(2, 2)).toEqual(4);
});

All expect() matchers supported by Jest are extensively documented here.
You can also use jest.fn() and expect(fn).toBeCalled() to create “spies” or mock functions.

Using Third Party Assertion Libraries

We recommend that you use expect() for assertions and jest.fn() for spies. If you are having issues with them please file those against Jest, and we’ll fix them.

However, if you are used to other libraries, such as Chai and Sinon, or if you have existing code using them that you’d like to port over, you can import them normally like this:

import sinon from 'sinon';
import { expect } from 'chai';

and then use them in your tests like you normally do.

Initializing Test Environment

If your app uses an API that you need to mock in your tests or if you just need a global setup before running your tests, add a src/setupTests.js to your project. It will be automatically executed before running your tests.

For example:

src/setupTests.js

const localStorageMock = {
  getItem: jest.fn(),
  setItem: jest.fn(),
  clear: jest.fn()
};
global.localStorage = localStorageMock

Focusing and Excluding Tests

You can replace it() with xit() to temporarily exclude a test from being executed.
Similarly, fit() lets you focus on a specific test without running any other tests.

Coverage Reporting

Jest has an integrated coverage reporter that works well with ES6 and requires no configuration.
Run npm test -- --coverage (note extra -- in the middle) to include a coverage report like this:

Note that tests run much slower with coverage so it is recommended to run it separately from your normal workflow.

Continuous Integration

By default npm test runs the watcher with interactive CLI. However, you can force it to run tests once and finish the process by setting an environment variable called CI.

When creating a build of your application with npm run build linter warnings are not checked by default. Like npm test, you can force the build to perform a linter warning check by setting the environment variable CI. If any warnings are encountered then the build fails.

Popular CI servers already set the environment variable CI by default but you can do this yourself too:

On CI servers

Travis CI

1. Following the Travis Getting started guide for syncing your GitHub repository with Travis. You may need to initialize some settings manually in your profile page.
2. Add a .travis.yml file to your git repository.

language: node_js
node_js:
  - 6.10
cache:
  directories:
    - node_modules
script:
  - npm test
  - npm run build

1. Trigger your first build with a git push.
2. Customize your Travis CI Build if needed.

On your own environment

Windows (cmd.exe)

set CI=true&&npm test

set CI=true&&npm run build

(Note: the lack of whitespace is intentional.)

Linux, macOS (Bash)

CI=true npm test

CI=true npm run build

The test command will force Jest to run tests once instead of launching the watcher.

The build command will check for linter warnings and fail if any are found.

Snapshot Testing

Snapshot testing is a feature of Jest that automatically generates text snapshots of your components and saves them on the disk so if the output changes, you get notified without manually writing any assertions on the component output. Read more about snapshot testing.

Editor Integration

If you use Visual Studio Code, there is a Jest extension which works with Create Alexa App out of the box. This provides a lot of IDE-like features while using a text editor: showing the status of a test run with potential fail messages inline, starting and stopping the watcher automatically, and offering one-click snapshot updates.

Deployment

npm run build creates a build directory with a production build of your app.

Advanced Configuration

You can adjust various development and production settings by setting environment variables in your shell or with .env.

Variable	Development	Production	Usage
CI	🔶	✅	When set to true, Create Alexa App treats warnings as failures in the build. It also makes the test runner non-watching. Most CIs set this flag by default.

Troubleshooting

npm start doesn’t detect changes

When you save a file while npm start is running, the console should refresh with the updated code.
If this doesn’t happen, try one of the following workarounds:

• If your project is in a Dropbox folder, try moving it out.
• If the watcher doesn’t see a file called index.js and you’re referencing it by the folder name, you need to restart the watcher due to a Webpack bug.
• Some editors like Vim and IntelliJ have a “safe write” feature that currently breaks the watcher. You will need to disable it. Follow the instructions in “Adjusting Your Text Editor”.
• If your project path contains parentheses, try moving the project to a path without them. This is caused by a Webpack watcher bug.
• On Linux and macOS, you might need to tweak system settings to allow more watchers.
• If the project runs inside a virtual machine such as (a Vagrant provisioned) VirtualBox, create an .env file in your project directory if it doesn’t exist, and add CHOKIDAR_USEPOLLING=true to it. This ensures that the next time you run npm start, the watcher uses the polling mode, as necessary inside a VM.

If none of these solutions help please open an issue.

npm test hangs on macOS Sierra

If you run npm test and the console gets stuck after printing alexa-scripts test to the console there might be a problem with your Watchman installation as described in facebookincubator/create-react-app#713.

We recommend deleting node_modules in your project and running npm install (or yarn if you use it) first. If it doesn't help, you can try one of the numerous workarounds mentioned in these issues:

• facebook/jest#1767
• facebook/watchman#358
• ember-cli/ember-cli#6259

It is reported that installing Watchman 4.7.0 or newer fixes the issue. If you use Homebrew, you can run these commands to update it:

$ watchman shutdown-server
$ brew update
$ brew reinstall watchman

You can find other installation methods on the Watchman documentation page.

If this still doesn’t help, try running launchctl unload -F ~/Library/LaunchAgents/com.github.facebook.watchman.plist.

There are also reports that uninstalling Watchman fixes the issue. So if nothing else helps, remove it from your system and try again.

npm run build silently fails

It is reported that npm run build can fail on machines with no swap space, which is common in cloud environments. If the symptoms are matching, consider adding some swap space to the machine you’re building on, or build the project locally.

npm run build fails on Heroku

This may be a problem with case sensitive filenames. Please refer to this section.

Moment.js locales are missing

If you use a Moment.js, you might notice that only the English locale is available by default. This is because the locale files are large, and you probably only need a subset of all the locales provided by Moment.js.

To add a specific Moment.js locale to your bundle, you need to import it explicitly.
For example:

import moment from 'moment';
import 'moment/locale/fr';

If import multiple locales this way, you can later switch between them by calling moment.locale() with the locale name:

import moment from 'moment';
import 'moment/locale/fr';
import 'moment/locale/es';

// ...

moment.locale('fr');

This will only work for locales that have been explicitly imported before.

Something Missing?

If you have ideas for more “How To” recipes that should be on this page, let us know or contribute some!