Setting up your TypeScript environment

This guide provides some basic steps for setting up your TypeScript development environment for use with the ArcGIS Maps SDK for JavaScript. The focus is on using @arcgis/core ES modules. The TypeScript definitions are included when you install @arcgis/core. This is not a TypeScript tutorial. It is highly recommended that you review the TypeScript tutorial material and Get Started pages.

There are many advantages to using TypeScript. Its primary function is identifying type errors before the code runs, which is often referred to as static type checking. The benefit is time and productivity savings when troubleshooting issues while the application is being built.

Prerequisites

If you have installed a JavaScript framework project, such as React or Angular, with TypeScript enabled, then there are no prerequisites that need to be installed.

If you are using TypeScript in a stand-alone project without a framework, then the recommended way to install TypeScript is to use 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.

Folder structure

Here is an example folder structure for a basic TypeScript application:

Use dark colors for code blocksCopy
root-folder/
  index.html
  package.json
  tsconfig.json
  src/
    main.ts

We will cover several of these files in this guide.

Install the ArcGIS Maps SDK for JavaScript

When you npm install the API locally, the TypeScript type definitions are included with the modules:

Use dark colors for code blocksCopy
npm install @arcgis/core

Build the Application

Create Web Page

The first step is to create your index.html and below is a basic example.

Use dark colors for code blocksCopy
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no"/>
    <title>ArcGIS JS API 4.31 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.31/@arcgis/core/assets/esri/themes/light/main.css">
  </head>
  <body>
    <div id="viewDiv"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Note, the <script> tag points to the main.ts source file and not a .js file. This is because during the build process that file will be converted from TypeScript to JavaScript.

Configure CSS

This example uses the CSS hosted on the ArcGIS CDN. Make sure the CSS URL is pointing to the correct API version.

Use dark colors for code blocksCopy
<link rel="stylesheet" href="https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/light/main.css">

If you need to use locally hosted CSS, then refer to the managing assets locally documentation. Depending on requirements you can also set the CSS in the project's main stylesheet or at the component level.

When styling the #viewDiv adjust the properties based on your requirements, for example:

Use dark colors for code blocksCopy
#viewDiv {
  padding: 0;
  margin: 0;
  height: 100%;
  width: 100%;
}

First TypeScript File

The API's types are automatically inferred, you don't need to set type annotations for every declaration. For example, in the code snippet below the variable map is inferred to be of type Map. ArcGISMap is simply the variable name that references the default export of the Map class, the name has no affect on the typings.

Use dark colors for code blocksCopy
import ArcGISMap from "@arcgis/core/Map.js";
import MapView from "@arcgis/core/views/MapView.js";

const map = new ArcGISMap({
  basemap: "streets-vector"
});

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

view.when(() => {
  console.log("Map is loaded");
})

Compiling

tsconfig

Before you can compile TypeScript to JavaScript, you will need to configure the TypeScript compiler. You can do this by creating a tsconfig.json. If a tsconfig.json file was created when you installed your project it is recommended to review all the settings.

Here is a minimal example of a tsconfig.json:

Use dark colors for code blocksCopy
{
  "compilerOptions": {
    "esModuleInterop": true,
    "lib": ["ES2020", "DOM"],
    "module": "ES2020",
    "moduleResolution": "Node",
    "strict": true,
    "target": "ES2020"
  },
  "include": ["./src"]
}

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, this allows use of import syntax such as import x from 'xyz'.
compilerOptions.module - This is the module system used to compile the code. In this example we are compiling the output as ES modules targeted at ES6 or higher.
compilerOptions.target - This sets the output at the minimum version of JavaScript features that will be supported. ES2019 works across all supported browsers.
include - Array of .ts files to compile. You can also use glob patterns such as "src/**/*".

Compile

If you are using a TypeScript-enabled framework then the types will automatically be compiled when you build the app.

If you are using TypeScript with the APIs AMD CDN modules in a stand-alone app, in the root of your application run tsc or tsc -w to watch for file changes.

You are now ready to start writing TypeScript applications.

Editor

A very popular editor for writing TypeScript is Visual Studio Code. Code has robust TypeScript integration that can assist with building your application.

Additional Information

Please refer to these links for additional information:

jsapi-resources GitHub repository contains various samples and other resources.
TSConfig reference
TypeScript reference
TypeScript helper functions
The Definitive TypeScript Guide