TypeScript - Setting up your development environment

In order to take advantage of the Accessor and custom widget development, you will want to first learn how to set up your development environment to use TypeScript.

This guide provides some basic steps you can use to set up your TypeScript development environment. This is not a TypeScript tutorial. It is highly recommended that you review some of the tutorial material available.

Prerequisites
- Folder structure
Install the ArcGIS API for JavaScript Typings
Install Dojo 1 Typings (Optional)
Write Application
- Create Web Page
- First TypeScript File
Compile TypeScript
Additional Information

Prerequisites

The recommended way to install TypeScript is via Node and npm. The package manager npm is used to install various libraries and tools.

Make sure to install TypeScript globally using npm install -g typescript. This will install a command line tool called tsc that will be used to compile your TypeScript code. You can then check you have TypeScript installed by using tsc -v and it should tell you the version of TypeScript you have installed.

The demo application for this guide can be found here.

Folder structure

We recommend you use the following folder structure for your application.

root-folder/
  index.html
  package.json
  tsconfig.json
  app/
    main.ts

We will cover each of these files in this guide.

Install the ArcGIS API for JavaScript Typings

You can run the following commands in the root of your application.

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

The first command will create a package.json in your folder. The second command will install the typings for the JavaScript API from npm into a node_modules folder. If you want to learn more about TypeScript Declaration Files, you can read more here.

Install Dojo 1 Typings (Optional)

You can optionally install Dojo 1 Typings to use Dojo 1 with TypeScript. See How to use for more detailed steps and README.md for more information.

Run the following command in the root of your application to quickly install.

npm install dojo-typings --save-dev

Write Application

Create Web Page

Please refer to the demo index.html file. You can also refer to the Dojo documentation on how to load custom modules when using the Dojo loader via CDN.

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="initial-scale=1, maximum-scale=1,user-scalable=no"/>
    <title>ArcGIS JSAPI 4.4 TypeScript Demo</title>
    <style>
      html,
      body,
      #viewDiv {
        padding: 0;
        margin: 0;
        height: 100%;
        width: 100%;
      }
    </style>
    <link rel="stylesheet" href="https://js.arcgis.com/4.4/esri/css/main.css">
    <script>
      var locationPath = location.pathname.replace(/\/[^\/]+$/, "");
      window.dojoConfig = {
        packages: [
          {
            name: "app",
            location: locationPath + "/app"
          }
        ]
      };
    </script>
    <script src="https://js.arcgis.com/4.4"></script>
  </head>
  <body>
    <div id="viewDiv"></div>
    <script>require(["app/main"]);</script>
  </body>
</html>

First TypeScript File

Now you will want to write your first TypeScript file (app/main.ts).

import EsriMap = require("esri/Map");
import MapView = require("esri/views/MapView");

const map = new EsriMap({
  basemap: "streets"
});

const view = new MapView({
  map: map,
  container: "viewDiv",
  center: [-118.244, 34.052],
  zoom: 12
});

Compile TypeScript

tsconfig

Before you can compile TypeScript to JavaScript, you will need to configure the TypeScript compiler. You can do this by create a tsconfig.json file.

Here is a sample tsconfig.json you could use for writing ArcGIS API 4 for JavaScript applications.

{
  "compilerOptions": {
    "module": "amd",
    "noImplicitAny": true,
    "sourceMap": true,
    "jsx": "react",
    "jsxFactory": "tsx",
    "target": "es5",
    "experimentalDecorators": true,
    "preserveConstEnums": true,
    "suppressImplicitAnyIndexErrors": true
  },
  "include": [
    "./app/*"
  ],
  "exclude": [
    "node_modules"
  ]
}

The options of the tsconfig.json are the same as the options passed to the TypeScript compiler. Without going into too much detail, the important options to take note of are as follows:

compilerOptions.module - Will compile TypeScript code to AMD modules as needed by the JavaScript API.
compilerOptions.target - Output to ES5 to work across all supported browsers.
include - Array of files to compile. Can use glob-like file patterns.

For more details, please refer to the tsconfig.json documentation.

Compile

In the root of your application, you can run the following command.

tsc - This command will look at your tsconfig.json file and compile your TypeScript based on its configuration.
tsc -w - This command does the same as above, but will also watch for file changes and recompile files as you edit them.

You are now ready to start writing TypeScript applications.

As your development needs grow, you can also use task runners, such as Grunt or Gulp.

Bonus

If you use the demo application, you can run tslint './app/*.ts' to lint your TypeScript files.

Editor

A very popular editor for writing TypeScript is Visual Studio Code. Code has robust TypeScript integration that can assist you while you build your application. Using the application from this demo in Code, you can configure a task runner to compile TypeScript for you.

Additional Information

Please refer to these additional links for further information: