Skip to content

Latest commit

 

History

History
144 lines (101 loc) · 6.74 KB

convert-javascript-to-typescript.md

File metadata and controls

144 lines (101 loc) · 6.74 KB
Raw
title description ms.topic ms.date ms.localizationpriority
Convert an Office Add-in project in Visual Studio to TypeScript
Learn how to convert an Office Add-in project in Visual Studio to use TypeScript.
how-to
08/06/2024
medium

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

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

Note

Skip this section if you already have an existing project.

  1. 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.

  2. Using the search box, enter add-in. Choose Excel Web Add-in, then select Next.

  3. Name your project and select Create.

  4. In the Create Office Add-in dialog window, choose Add new functionalities to Excel, and then choose Finish to create the project.

  5. 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 package

  1. Open the Nuget package manager by choosing Tools > Nuget Package Manager > Manage Nuget Packages for Solution
  2. Select the Browse tab. Search for and select 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.

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

  1. In Solution Explorer, right-click (or select and hold) 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.

  2. In the Add New Item dialog, search for and select TypeScript JSON configuration File. Select Add to create a tsconfig.json file.

  3. 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/**/*",
    "**/*"
  ]
}

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

Create an npm configuration file

  1. In Solution Explorer, right-click (or select and hold) 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.

  2. In the Add New Item dialog, search for npm Configuration File. Select Add to create a package.json file.

  3. Update the package.json file to have the @types/jquery package in the devDependencies section, as shown in the following JSON.

    {
  "version": "1.0.0",
  "name": "asp.net",
  "private": true,
  "devDependencies": {
    "@types/jquery": "^3.5.30"
  }
}

  4. Save the file.

  5. Select the ASP.NET web project that has your project name with the text Web appended to the end. Under the npm section, set both Restore On Project Open and Restore On Save to "True".

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.

  1. Find the Home.js file and rename it to Home.ts.

  2. Find the ./Functions/FunctionFile.js file and rename it to FunctionFile.ts.

  3. Find the ./Scripts/MessageBanner.js file and rename it to MessageBanner.ts.

  4. 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;
    ...

  5. 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

  1. 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.

  2. In Excel, choose the Home tab, and then choose the Show Taskpane button on the ribbon to open the add-in task pane.

  3. In the worksheet, select the nine cells that contain numbers.

  4. Press the Highlight button on the task pane to highlight the cell in the selected range that contains the highest value.

See also