TypeScript

TypeScript allows you to catch bugs in your JavaScript code without having to run your Homey Apps. The Homey CLI makes it easy to get started developing Homey Apps with TypeScript.

TypeScript in the Homey CLI

TypeScript enables you to add types to your code which may aid you when developing your app. The Homey CLI allows you to choose between JavaScript and TypeScript when creating a new app. It is also possible to convert an existing app written in Javascript to TypeScript. This can even be done on a file by file basis.

How it works

TypeScript 'transpiles' to JavaScript. This means that the TypeScript you write will be converted to JavaScript that runs on Homey. When your app is being processed to run on a Homey, it is possible to invoke a TypeScript compiler as an extra build step. The compiler compiles your files to a folder called .homeybuild/ in the root folder of your app. After this compilation, Homey will bundle all JavaScript files into one app.

Creating new drivers with TypeScript

When the file tsconfig.json is present in the root folder of your app, the Homey CLI will default to TypeScript when running homey app driver create. If you want to avoid this, remove or rename tsconfig.json file.

Removing or remaning the tsconfig.json file will also prevent the TypeScript compiler from being invoked when running/installing/publishing your app.

Creating a new app using TypeScript

Run homey app create in your terminal and answer 'Yes' when the CLI asks you to initialize your app with TypeScript utilities. All necessary and recommended dependencies and files will be created for you.

Converting an existing app to TypeScript

If you have already created your app using JavaScript, but you want to convert your app to TypeScript, then this can only be performed manually. However, the conversion to TypeScript can be done file-by-file using the following steps:

Create a .tsconfig.json

The first thing to do is adding a file named .tsconfig.json to the root folder of your App. This will make Homey recognize your app as a TypeScript app. You are free to configure tsconfig.json to your liking. Only exception being the outDir which should remain .homeybuild/and having sourceMap: true is strongly recommended.

/tsconfig.json

{
  "extends": "@tsconfig/node12/tsconfig.json",
  "compilerOptions": {
    "outDir": ".homeybuild/",
    "sourceMap": true
  }
}

Install dependencies

Make sure you have the file .tsconfig.json present in the root folder of your app. Then run the following command to install all necessary dependencies.

homey app add-types

Change your App entrypoint:

Rename app.js to app.ts and add the following lines at the top (You can remove 'use strict').

/app.ts

import sourceMapSupport from 'source-map-support';
sourceMapSupport.install();
...

Add the build step

Add a TypeScript transpile step in the npm build script.

/package.json

  "scripts": {
    "build": "tsc"
  },

All set!

Now you're all set! Run your app with homey app run. If you performed all steps correctly, then you should see a Compiling TypeScript... prompt before your app is being run.