Menu

Using tslib for TypeScript 2.1 with Aurelia to save bandwidth

22 December 2016

The TypeScript release notes for version 2.1 contains an interesting section named 'Support for external helpers library (tslib)'. This new feature allows you to use require.js to get the polyfills or helper functions that are normally generated by TypeScript in each file to support backward compatibility (using ESnext features supported by TypeScript, but not yet by all browsers).

Support for external helpers library (tslib)
TypeScript injects a handful of helper functions such as _extends for inheritance, _assign for spread operator in object literals and JSX elements, and __awaiter for async functions.

Previously there were two options:

inject helpers in every file that needs them, or no helpers at all with --noEmitHelpers.

The two options left more to be desired; bundling the helpers in every file was a pain point for customers trying to keep their package size small. And not including helpers, meant customers had to maintain their own helper's library.

TypeScript 2.1 allows for including these files in your project once in a separate module, and the compiler will emit imports to them as needed.

What's the difference?

If we take a very basic class written in Aurelia with some ES features that are currently not supported in all browsers:

TypeScript will generate some helper methods (to make sure it works everywhere) in the outputted JavaScript (which will be repeated for every class inside your bundle, because TypeScript isn't aware of your bundling system):

As you can probably imagine, this will result in a lot less JavaScript code when you have a decent sized application (because it only needs to transfer(have) the helper/ polyfill once in the tslib package).

See it in action

We will add this to a new Aurelia TypeScript project generated by the Aurelia-CLI.

Aurelia TypeScript project

First, create a default Aurelia project with the Aurelia-CLI by using the command:

au new

And use the option Default TypeScript to generate the default configuration for a TypeScript project.

Adding the tslib dependency

We can install the tslib dependency by performing the following command:

npm i tslib -S

Setup tslib

Next, we will modify the compiler options, in the tsconfig.json file to enable this feature to work. Add the following option:

{
"compilerOptions": {
"importHelpers": true,
....
}
}

Open the aurelia.json file, located in the aurelia_project folder, and add the dependency "tslib" on top.