So why do we use Typescript? What Typescript allows developers to do is to develop with the most modern language features that aren't yet supported in browsers. The transpiler assures that that modern Typescript code that you write? Well, it will work across all browsers. Typescript also offers a great development experience that developers would use in certain environments, such as a C# development environment. "Find All References," "Go To Definition," "Global Rename" are just a few of the advantages you have when developing your application in Typescript. Being able to create types allows this for this rich development experience.
If you've built a GIS widget before, you'll notice the tool chain for building a widget now is dramatically different. Never fear! I will explain each part of the process in a clear and easy to understand manner!
The tutorial I'm following a long with is from the Esri site. What I'll be doing is trying to explain some of the concepts along the way.
Step 1: Create a new directory on your computer where you'd like to host the widget project. I'll go ahead and call mine HelloGalaxy (as opposed to HelloWorld).
Step 2: Open VS Code and then within VS Code select File > Open Folder. Open the folder location you had just created for your widget.
Step 3: Create a new file called tsconfig.json. Each Typescript project you'll create will need this json file to operate. There a number of configuration options but the important one to note is the jsx, react, and target config options. Notice the target is ES5, which stands for ECMAScript Version 5. To learn more about ECMAScript and what that really mean, this link is helpful.
Step 4: A shortcut to get a command line window with bash capabilities is to select View > Integrated Terminal. Within the terminal type: npm init --yes. This will create a shell package.json for you. You should see the package.json it created. Go ahead and inspect it to see what it created. Then in the terminal type: npm install --save @types/arcgis-js-api. Notice what was just saved to the package.json file. That package is now included in the dependencies section of the package.json. Now if you look within the directory you created you'll see a node_modules folder. Within there if you drill down you'll see an index.d.ts file which contains the type definitions we'll need for Typescript to work properly with our widget project. This will also give us some excellent intelligence when developing our widget!
Step 5 (optional): While we're at it let's make this folder a git repo. If you have git installed just type: git init in the terminal window. If you do this, create a new file called .gitignore and then within that file type node_modules. Then we'll ignore the node_modules folder from our new source control repo we just created.
A screenshot of what my VS Code looks like after Step 5:
Full contents of HelloGalaxy.txs with comments explaning the functions of the code:
Step 7: With your terminal open, type in the tsc command. Once you run that command you should see a HelloGalaxy.js file and a HelloGalaxy.map file in your app folder. Inspect the HelloGalaxy.js file to see what the Typescript compiler has spit out just from the contents of the tsx file. It's doing this so any browser that supports ES5 (which is all of them) can interpret the code.
Step 8: Create a new file named index.html in the app directory. Set the contents of the file as follows:
Step 9: Open the index.html in a browser. You should see the following in your browser:
What we just went through was an exercise about working with the new widget framework. This framework includes Typescript, TSX files, and compiling that to interact with your index.html.
In this example, the index.html was the entire widget. A more complicated example on the Esri site explains how to place the widget on a map. They use view.ui.add([WidgetClassName]) where we just simply set ours to the widgetDiv container.
Hopefully you can see how this widget model will be useful in developing widgets. What Esri is trying to do is make widget development into component driven design. To download the full project or simply browse through the code examples browse to our GitHub repository where this code is hosted.