Building a web application, TypeScript is a clear step forward from JavaScript: its static type system catches a wide range of errors directly in your editor, before the code ever runs. But there is one drawback: browsers don't understand it natively, which means you'll need to set up a few tools...
Using TypeScript to write a web application requires a transpilation step before the code can be used in an HTML page. Furthermore, if the source code consists of multiple files or modules, a bundler is typically used to statically resolve the dependencies between modules. All these tools must be configured correctly to work together, and it's easy to waste time setting up the structure when starting a new project. To make this easier, we have created for you a template project with everything set up properly.
This small example project is intended to provide a ready-to-use basic structure that meets the criteria we consider most important:
- Convenient: a single click should be enough test a code change;
- Lightweight: the project should be simple and minimize external dependencies;
- Interoperable: the project should allow the integration of external libraries, integrated either via source files or via a package manager;
- Portable: the project must not require a specific version of Node.js or TypeScript, but should ideally work with all versions supported for at least the past 5 years.
You will find this template project in our TypeScript library, in subdirectory example_html/Project-BoilerPlate. We have also published it as a separate GitHub repository in case it is more convenient for you to clone it.
Setting up the development environment
Depending on the operating system you are using, you may want to use a specific version of Node.js:
- on recent 64 bit operating systems (Windows 10+, Linux, etc.):
Install any supported version of Node.js (as of today, version 24 or higher); - on recent 32-bit operating systems:
Use Node.js version 22 (the last version with 32-bit support); - on Windows 7:
Install Node.js version 12, the last supported LTS version for Windows 7. In that case, you should also edit package.json to pin the following dependency versions:"@types/node": "^12.0.0",
"esbuild": "0.21.5",
"typescript": "5.0.4"
Once Node.js is installed, open a command shell in the project directory and run:
npm install
This will install the project dependencies, namely the TypeScript compiler and the esbuild bundler.
If you come across dozens of warnings while esbuild installs, make sure you are using the proper version of Node.js as recommended above, and that you applied the package.json changes for Node 12. The esbuild package may still issue some warnings in that case, but they will not prevent it from working properly.
Project structure
| Path | Description |
|---|---|
| src/** | Full source code (TypeScript) |
| obj/** | Individual transpiled files |
| dist/** | Distribution folder (runtime files) |
| tools/** | Development tools for this project |
| package.json | Project description, including dependencies |
| tsconfig.json | Global TypeScript settings file |
The top-level entry point for the web app is dist/app.html. It will start the bundled TypeScript code.
The TypeScript entry point is src/app.ts.
Testing and debugging the application
The template project includes a npm command very convenient for testing TypeScript code. To use it, open a command shell and type:
npm run app-server
This command will:
- Build the project
- Start a tiny Web server (provided in tools directory)
- Open a Web browser and start the application from the tiny Web server
- Watch TypeScript source files to incrementally rebuild the application whenever a source file changes
When you make any change to the source code using the editor of your choice, simply save the TypeScript file and press reload in the browser. The watcher will take care of recompiling the application under the hood.
Integrating third-party libraries
If you want to keep full control on the source code in your application, you can integrate third-party libraries directly as TypeScript source code, by adding subdirectories to src. This is the approach we have chosen in this example to integrate Yoctopuce library.
To integrate a third-party library via a package manager, use the usual npm install ... command. The package will then be automatically integrated as needed by the bundler.
Note: To illustrate third-party integration, a dependency on the uuid library has been artificially added to this project. This library is not required by the compilation framework itself - make sure to uninstall it to avoid keeping it unnecessarily in your final project.
Building the project using a command line
If you want to build the whole project, simply type:
npm run build
Once done, you will find the distribution files in the dist/ subdirectory.
You can then upload them to any Web server, or to your favorite YoctoHub.
Minification
Note that we have enabled in esbuild settings the production of a minified bundle file app.min.js. As long as the corresponding .map file is served to the browser from the same location, using a minified file does not hinder debugging at all: errors and debugging can be done directly in the TypeScript source files. But if for some reason you prefer to disable minification, you can do so. Simply:
- change the minify parameter to false in app-server.ts (for the watcher)
- remove the --minify option in package.json (for command-line builds)
