If you're a JavaScript developer, you may have heard of TypeScript, a typed superset of JavaScript that compiles to plain JavaScript. If you're also creating custom Web AppBuilder widgets, using TypeScript in a widget is a great way to get started with TypeScript. Here are a few notes and tips that I've discovered while using TypeScript within a Web AppBuilder custom widget development workflow.
My usual Web AppBuilder development workflow is to have my widget code in its own code repository, and use a task runner like Grunt or Gulp to automatically compile and copy my code to the correct places (The stemapp directory and optionally the server directory of the app that I'm currently working on). Within this context, TypeScript fills the "transpiler" role where Babel might currently be in your stack.
Many aspects of your tsconfig.json file are on a per-project basis, but there are a few things that you do need:
Full example here.
This is the main key to the entire process. It tells the TypeScript compiler how to translate your ES6-style class syntax in your Widget.ts file into the Dojo-style define/declare syntax that Web AppBuilder expects. This bit of code can be obtained from the dojo/typings repository, and included in your widget files. You then import it into your Widget.ts file, and apply the decorator on your Widget class. Note that decorators are experimental right now, so they could potentially be removed from TypeScript in the future, but for now this is a good option that keeps our code clean.
I would like to write code as close as possible to true ES6 JavaScript. So I'd like to use the native JavaScript Promise syntax. But when I tried to do this in my widget, I initially got an error, "error TS2693: 'Promise' only refers to a type, but is being used as a value here." To resolve this problem, all I had to do was add the "es6-promise" library to my "lib" property in the "tsconfig.json" file. See the "--lib" line in the TypeScript Compiler Options Table for more information - including a clarification of why I'm including dom, es5, etc, as well as options that you can add other than es2015.promise.
["dom", "es5", "scripthost", "es2015.promise"]
I found it's easiest if you set "inlineSources" and "inlineSourceMap" in your "tsconfig.json" file to true. If not, the path of the sourcemap is often wrong. The TS source shows as a separate file from your main widgets file:
That's a lot of information, and it's sometimes hard to get all the settings in your project exactly correct, so I've put together an example widget in a GitHub repository that is available for download here: Web AppBuilder Typescript Examples. Note there are 2 examples in there that represent 2 "styles" of project, so please read the README file for clarification on which to use. We're also considering getting a TypeScript option into the Web AppBuilder Custom Widget Generator, and if you have any feedback on what you'd like to see there, please let us know via this GitHub issue. Thanks!
Thanks to developer community members David Wilton, Alex Jones, and Mike Tschudi for help on the code and repository.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.