Usage with TypeScript

Using TypeScript is an industry standard in 2024. It provides a lot of benefits over JavaScript, such as static type checking, better code completion, and improved code readability. This guide will show you how to use TypeScript with the Moddable SDK.

Prerequisites

There are various ways to start a new project with TypeScript. There are also many way to do it using the Moddable SDK. The following guide is opinionated and will use a specific setup. You can adapt it to your needs. But this looks like a good starting point close to the web development environment.

In the following statement of this guide we will use pnpm as our package manager. You can use any other while this is recommended. Adapt your commands accordingly if so.

Let’s get started

This starter project aim to build a single JS file that will be passed to XS. This helps developers coming from the web to have a more familiar environment and also to have a better development experience.

For this purpose, we will use a bundler tool which is very popular in the JavaScript community, especially in the web development where you want to reduce the number of network request and optimize the JS bundle from the server. There are many tools available to help you with this task. Tools like Webpack, Rollup, and esbuild are popular choices for bundling JavaScript code. For this guide, as the bundler we will use Bun, which is a JavaScript Environment, but also a bundler/transpiler. It is a very simple tool that allows you to write your code in TypeScript and bundle it into a single file. If you use mise-en-place, you can install it with the following command:

mise install bun

Otherwise follow the instructions on the Bun website.

Now we will use a starter template that has setup everything for us upfront.

 bunx tiged ScreamZ/xs-dev-TypeScript-template ts-xs-project

Specializing the starter template for your project

The first thing you need to do is to update the package.json file with your project details. You can do this by following those instructions:

Update name property with your project name.
Update author property with your name.
Follow the remaining instruction on the GitHub https://github.com/ScreamZ/xs-dev-Typescript-template

How does it work?

The template is a simple project that uses Bun to bundle the TypeScript code into a single file. The TypeScript code is located in the src folder, and the bundled code is located in the dist folder.

The starter exposes a pnpm dev command that watch for changes in the src folder and automatically recompile the code. This is very useful when you are developing your project. You should keep this command running in a terminal window while you are working on your project.

When you need to try the code, simply run xs-dev run in the terminal. This will upload the bundled code from dist/main.js to the device and run it. The rest remains the same as the standard xs-dev workflow.

Take note that whenever you import some code from the Moddable SDK, you will need to add the following line in the tsconfig.json file:

"types": [
     // ... Previous lines
      "./node_modules/@moddable/typings/<path-to-the-file>"
    ]

Those typings are provided by @moddable/typings package, and while at the moment this is a bit cumbersome, it’s up to you to find the correct definition file for the module you are using.

As an example, the Timer and WiFi modules live in ./node_modules/@moddable/typings/wifi and ./node_modules/@moddable/typings/timer

The team is actively working on improving the development workflow.

Deploying to production

When you are ready to deploy your project to production, you can run the following command:

pnpm run build:release

This will bundle the TypeScript code into a single file and minify it (compress into a single line of code and compress variables names). The bundled code will be located in the dist folder. You can then upload this code to your device following the standard xs-dev workflow.

As an example to build for an ESP32 device:

xs-dev build --device esp32