Detailed Guide on How to Use TypeScript with Dynamics 365 - Part 1: Setting up the Environment

Arsen Aghajanyan
 on Fri Oct 26 2018


TypeScript is a typed superset of JavaScript that compiles into JavaScript. TypeScript has several benefits including easier OOP methodology, common errors spotting at compile time, support for new ECMAScript standards, etc.

As a Dynamics 365 Developer, it is quite exciting to use TypeScript within the system. By default, Dynamics don’t support TypeScript. Let’s see how we can sidestep this. There are plenty of approaches available, but I'll show the way I do it.

Setting up the environment

Open Visual Studio. From the menu select File > New > Project. Select Other Project Types > Visual Studio Solutions > Blank Solution. Name it WebResources


Open the solution in the File Explorer and create WebResources folder in the solution directory. Right Click on the solution from Solution Explorer and select Add > Existing Web Site. Choose the WebResources folder.



Add ts and js folders under WebResources project. These are the folders where we will store our TypeScript and compiled JavaScript files.


Also, add tsconfig.json file and replace its content with the code snippet provided below. This file configures the compilation process. complieOnSave property controls whether it should compile the code into JavaScript on saving or no. compilerOptions properties control the directory where compiled JavaScript should be stored, the targeted ECMAScript version and the generation of mapping file between TypeScript code and JavaScript code. For more information on  tsconfig.json  check the official documentation at here.

  "compileOnSave": true,
  "compilerOptions": {
    "outDir": "js",
    "target": "es5",
    "sourceMap": true
  "include": [

Right click on the ts folder and select Add > TypeScript File. Name it Account.ts. This is the file where goes all the TypeScript code.



namespace Account {
  export function getClientUrl() {


After you save Account.ts file it will automatically generate JavaScript files under the js folder. This is controlled by compilation options in the tsconfig.json file.


Add @types/xrm library using Visual Studio Library Manager. Right Click on the project and select Client Side Library. Note that you should change the provider to unpkg to include packages from npm. Additionally, you should also provide a version of the library. In this case @types/xrm@9.0.7.



This will install the necessary xrm TypeScript packages under your project


Note: Library Manager Feature is available since Visual Studio 2017 15.7 release. If you don’t see this option you can install the necessary packages in any other way like npm or bower.

Add a reference to the index.d.ts file in our Account.ts file. You can do this by simply dragging the index.d.ts file and dropping it into opened Account.ts file. You should have something like this at the end.

/// <reference asset-path="../lib/@types/xrm/index.d.ts" />
namespace Account {
  export function getClientUrl() {
      var url = Xrm.Page.context.getClientUrl();

The environment setup is done. In the next parts, we will see how to deploy the web resource into Dynamics 365 and how to debug it directly in the browser. Stay tuned! :)