Learning JSAPI (with TypeScript), Lesson 1 of Many ...

Blog Post created by agelfert on Apr 25, 2019

Caveat Emptor

I don't go by the title web developer. I'm just a GIS guy using Developer tools to develop stuff. I say this because if you read my prose, you will, no doubt, on countless occasions, find yourself exclaiming: "Dude, don't you know that?!" or "Man, every developer understands that!". A lot of times, I may not. 'Cause I'm just a GIS guy... if it talks like a developer and quacks like a developer, it can still just be a GIS guy who... you get the picture.


Think of this post and future issues not as authoritative instruction but rather as a collection of gotchas and eurekas that I am living through as I'm teaching myself how to build web GIS tools using the Javascript API.


My goals at this point are ...

  • To learn the API to build custom tools and widgets.
  • To learn some Typescript hoping it will be more pleasant for Pythonistas like me than learning "old school" Javascript.
  • Pick up enough React to build apps that are more than an html template with a mapdiv sandwiched in the middle.


Below are my steps for launching this educational effort. You can find all of this elsewhere. This is merely a collection of what's worked for me and a summary of what I have. I'm always glad to hear what's missing from my setup! And do let me know about anything I got wrong.


i. Installed Visual Studio Code

For my IDE I chooise Visual Studio Code, of course. Everyone seems to be doing so these days. You can get it here. It has a clean interface and seems endlessly extensible if you need more functionality that you get out of the box. Not nearly as overwhelming as some of the other IDE's I've looked at over the years. Comes with plugins (extensions) galore.

ii. Installed Git

Download load it here. This time I was going to get this right. I've never done much development as part of a team, so source control has too often been an afterthought, and at times I've paid dearly. Plus, using Git with Code is so easy and seamless. <F1> and then <g> gives you all the Git commands at your fingertips. Most of what I do is just stage, commit, undo, checkout... the basics.

Right now, I have Git installed locally but I have it on the to-do list to implement it for multiple users. -- As a good habit, I've started including configuration files (see below, e.g. package-lock.json, tsconfig) in my version control. These change a lot when working with node/npm.

iii. Installed node/npm

This helps you manage all your JS modules. There are plenty of places where you can read up on npm commands, such as

npm install <modulename>@latest -g

For example, here When deciding what to install locally and what to install in your project, I found the suggestion helpful: if it's needed for the project to run, install locally; if you need it for your development environment, install globally.  As for the arcgis types, they went in my project.

But I get the sense people are very flexible about this and install much more locally than they may need here.

iv. Installed Typescript

In Visual Studio terminal run

npm install -g typescript

Note the difference between the module to be installed called typescript and the actual typescript compiler tsc.exe that you run using "tsc". This will compile everything with a *.ts extension to Javascript. To include/exlude files you specify as such in the tsconfig.json file.


To learn all about tsconfig, see here. An ESRI example is here. Getting the compilerOptions set right might be a bit of a learning curve and require trial and error. It was for me. Documentation is here.

v. Installed arcgis-js-api types

This is documented at length in places such as here or here. Once you've created a project folder, run "npm init --yes" to set up the project by creating a package.json file. All about package.json. Then you run:


npm install --save @types/arcgis-js-api

This installs the typescript types for JSAPI in your directory.

This gives you great intellisense and debugging help when compiling or linting.

vi. Installed Live Server

Installing this extension will synch VS Code with your browser either inside of Code or in the stand-alone browser. Every time you save your project, the browser refreshes the page.

Here is a good link that explains the use of live server with typescript compiler.


vii. Installed Eslint
Linters help you "analyze source code to flag programming errors, bugs, stylistic errors, and suspicious constructs...." (wikipedia). Visual Studio Code may suggest that you install tslist or complain if you don't. But in fact, tslint got folded into eslint. (I know, I know...) So go ahead and run...

npm install eslint@latest -g

To execute, navigate to your app's directory and do: 

eslint main.ts //or whatever your ts file is called

viii. "Runners" - Automatic Compile

If you don't want to constantly save you typescript files and then have to recompile the code. You can automate this. It used to be you had to configure a task runner. Now you just ad the following to your compiler options in tscnfig file:

"watch": true

and start "watching". You use <Ctrl><Shift><b> to start that...

Now as soon as you save your typescript file(s), the compilation runs, too.


Okay, that was Part 1. I'll do my best to continue with Part 2 shortly.