Custom Web AppBuilder Widgets in TypeScript
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:
- “module”: “amd” - we choose “amd” because AMD is the module style that Web AppBuilder expects to see when loading a widget into an app.
- “moduleResolution”: “classic” - because we chose “AMD” above
- “types”: [ “arcgis-js-api”, “dojo-typings”] - the names of the type definitions we want to include.
- “inlineSources” and “inlineSourceMap” - set these to true if you’ve got a build system that is moving code around, so that your source maps will work when debugging in the browser.
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.
[“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!
Note: this post also appears on my Esri Community Blog.
I periodically write about technology, maps, open data, and other software topics. To get updates about new posts: