Convert an Office Add-in project in Visual Studio to TypeScript

Article
03/14/2023

You can use the Office Add-in template in Visual Studio to create an add-in that uses JavaScript, and then convert that add-in project to TypeScript. This article describes this conversion process for an Excel add-in. You can use the same process to convert other types of Office Add-in projects from JavaScript to TypeScript in Visual Studio.

Prerequisites

Visual Studio 2022 or later with the Office/SharePoint development workload installed

Tip

If you've previously installed Visual Studio, use the Visual Studio Installer to ensure that the Office/SharePoint development workload is installed. If this workload is not yet installed, use the Visual Studio Installer to install it.
Excel 2016 or later.

Create the add-in project

In Visual Studio, choose Create a new project. If the Visual Studio development environment is already open, you can create a new project by choosing File > New > Project on the menu bar.
Using the search box, enter add-in. Choose Excel Web Add-in, then select Next.
Name your project and select Create.
In the Create Office Add-in dialog window, choose Add new functionalities to Excel, and then choose Finish to create the project.
Visual Studio creates a solution and its two projects appear in Solution Explorer. The Home.html file opens in Visual Studio.

Convert the add-in project to TypeScript

Add Nuget packages

Open the Nuget package manager by choosing Tools > Nuget Package Manager > Manage Nuget Packages for Solution
Select the Browse tab and search for Microsoft.TypeScript.MSBuild. Install this package to the ASP.NET web project, or update it if it's already installed. The ASP.NET web project has your project name with the text Web appended to the end. This will ensure the project will transpile to JavaScript when the build runs.
On the Browse tab, search for jquery.TypeScript.DefinitelyTyped. Install this package to the ASP.NET web project, or update it if it's already installed. This will ensure the jQuery TypeScript definitions are included in your project. The packages for jQuery appear in a file generated by Visual Studio, called packages.config.

Note

In your TypeScript project, you can have a mix of TypeScript and JavaScript files and your project will compile. This is because TypeScript is a typed superset of JavaScript that compiles JavaScript.

Create a TypeScript config file

In Solution Explorer, right-click the ASP.NET web project and choose Add > New Item. The ASP.NET web project has your project name with the text Web appended to the end.
In the Add New Item dialog, select TypeScript JSON configuration File to create a tsconfig.json file and then choose Add.

Update the tsconfig.json file to also have an include section as shown in the following JSON.

{
  "compilerOptions": {
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5"
  },
  "exclude": [
    "node_modules",
    "wwwroot"
  ],
  "include": [
    "scripts/**/*",
    "**/*"
  ]
}

Save the file. For more information on tsconfig.json settings, see What is a tsconfig.json?

Update the JavaScript files

Change your JavaScript files (.js) to TypeScript files (.ts). Then, make the necessary changes for them to compile. This section walks through the default files in a new project.

Find the Home.js file and rename it to Home.ts.
Find the ./Functions/FunctionFile.js file and rename it to FunctionFile.ts.
Find the ./Scripts/MessageBanner.js file and rename it to MessageBanner.ts.
In Home.ts, find the line Office.initialize = function (reason) { and add a line immediately after it to polyfill the global window.Promise, as shown here.
```
Office.initialize = function (reason) {
    // Add the following line.
    (window as any).Promise = OfficeExtension.Promise;
    ...
```
In ./Scripts/MessageBanner.ts, find the line _onResize(null); and replace it with the following:
```
_onResize();
```

The JavaScript files generated by Visual Studio do not contain any TypeScript syntax. You should consider updating them. For example, the following code shows how to update the parameters to showNotification to include the string types.

 function showNotification(header: string, content: string) {
        $("#notification-header").text(header);
        $("#notification-body").text(content);
        messageBanner.showBanner();
        messageBanner.toggleExpansion();
    }

Run the converted add-in project

In Visual Studio, press F5 or choose the Start button to launch Excel with the Show Taskpane add-in button displayed on the ribbon. The add-in will be hosted locally on IIS.
In Excel, choose the Home tab, and then choose the Show Taskpane button on the ribbon to open the add-in task pane.
In the worksheet, select the nine cells that contain numbers.
Press the Highlight button on the task pane to highlight the cell in the selected range that contains the highest value.