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.


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.

As of version 4.16, the tslib runtime library that contains all of the TypeScript helper functions must be installed as well. This can be installed via npm install --save tslib. For additional information on this, please refer to the tslib documentation.

The demo application for this guide can be found here.

Folder structure

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


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.

If you're upgrading an app from a previous version of the API to the latest version you can run the following command in your TypeScript project.

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

or if wanting to target a specific version, run

npm install @types/arcgis-js-api@4.[subversion-number-here] --save-exact

The web has an abundance of useful information regarding how to work with npm. An Absolute Beginners Guide to Using npm and How to Update npm Packages to their Latest Version are just a couple sites that discuss working with npm.

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.

    <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.19 TypeScript Demo</title>
      #viewDiv {
        padding: 0;
        margin: 0;
        height: 100%;
        width: 100%;
    <link rel="stylesheet" href="https://js.arcgis.com/4.19/esri/themes/light/main.css">
      var locationPath = location.pathname.replace(/\/[^/]+$/, "");
      window.dojoConfig = {
        packages: [
            name: "app",
            location: locationPath + "/app"
    <script src="https://js.arcgis.com/4.19"></script>
    <div id="viewDiv"></div>

First TypeScript File

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

import EsriMap from "esri/Map";
import MapView from "esri/views/MapView";

const map = new EsriMap({
  basemap: "streets-vector"

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

Compile TypeScript


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

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

  "compilerOptions": {
    "module": "amd",
    "lib": ["ES2019", "DOM"],
    "noImplicitAny": true,
    "esModuleInterop": true,
    "sourceMap": true,
    "jsx": "react",
    "jsxFactory": "tsx",
    "target": "ES5",
    "experimentalDecorators": true,
    "preserveConstEnums": true,
    "suppressImplicitAnyIndexErrors": true,
    "importHelpers": true,
    "moduleResolution": "node"

  "include": [
  "exclude": [

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.esModuleInterop - When true, allows use of import syntax such as import x from 'xyz'.
  • compilerOptions.module - Will compile TypeScript code to AMD modules as needed by the JavaScript API.
  • compilerOptions.target - Output to ES2019 to work across all supported browsers.
  • include - Array of files to compile. Can use glob-like file patterns.

"noImplicitUseStrict": true. See Mozilla strict mode documentation for further information regarding working in strict mode.

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


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.


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


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: