Custom functions debugging

Article
10/12/2023

This article discusses debugging only for custom functions that don't use a shared runtime. To debug custom functions add-ins that use a shared runtime, see Configure your Office Add-in to use a shared runtime: Debug.

Important

Note that Excel custom functions are available on the following platforms.

Office on the web
Office on Windows
- Microsoft 365 subscription
- retail perpetual Office 2016 and later
- volume-licensed perpetual Office 2021 and later
Office on Mac

Excel custom functions aren't currently supported in the following:

Office on iPad
volume-licensed perpetual versions of Office 2019 or earlier on Windows

Note

We recommend using custom functions with a shared runtime, unless you have a specific reason not to use a shared runtime. Note that using a shared runtime means your add-in will use WebView2 (Microsoft Edge Chromium-based) if conditions are met, and otherwise your add-in will use Trident (Internet Explorer 11) regardless of the Windows or Microsoft 365 version. For a description of the WebView2 conditions, see Browsers and webview controls used by Office Add-ins. For more information about runtimes, see Runtimes in Office Add-ins and Runtimes.

Tip

The debugging techniques that are described in this article don't work with projects that are created with the Office Add-in project containing the manifest only option in the Yeoman generator. The scripts that are referred to later in this article aren't installed with that option. To debug an add-in that is created with this option, see the instructions in one of the following articles, as appropriate.

The process of debugging a custom function for add-ins that don't use a shared runtime varies depending on the target platform (Windows, Mac, or web) and on whether you are using Visual Studio Code or a different IDE. Use the links in the following table to visit sections of this article that are relevant to your debugging scenario. In this table, "CF-NSR" refers to custom functions in a non-shared runtime.

Target platform	Visual Studio Code	Other IDE
Excel on the web	Use VS Code and the browser development tools	Use the command line tools
Excel on Windows	Use VS Code and the browser development tools	Debugging CF-NSR that are running in Excel on Windows outside VS Code isn't supported. Debug against Excel on the web.
Excel on Mac	VS Code debugging of CF-NSR that are running in Excel on Mac isn't supported. Debug against Excel on the web.	Use the command line tools

Use the browser developer tools to debug custom functions in Excel on the web

You can use the browser developer tools to debug custom functions that don't use a shared runtime in Excel on the web. The following steps work for both Windows and macOS.

Run your add-in from Visual Studio Code

Open your custom functions root project folder in Visual Studio Code (VS Code).
Choose Terminal > Run Task and type or select Watch. This will monitor and rebuild for any file changes.
Choose Terminal > Run Task and type or select Dev Server.

Sideload your add-in

Open Office on the web.
Open a new Excel workbook.
Select Home > Add-ins, then select Get Add-ins.
On the Office Add-ins dialog, select the MY ADD-INS tab, choose Manage My Add-ins, and then Upload My Add-in.
Browse to the add-in manifest file, and then select Upload.

Note

Once you've sideloaded to the document, it will remain sideloaded each time you open the document.

Start debugging

Open developer tools in the browser. For Chrome and most browsers F12 will open the developer tools.
In developer tools, open your source code script file using Cmd+P or Ctrl+P (functions.js or functions.ts).
Set a breakpoint in the custom function source code.

If you need to change the code you can make edits in VS Code and save the changes. Refresh the browser to see the changes loaded.

Use the command line tools to debug

If you aren't using VS Code, you can use the command line (such as bash, or PowerShell) to run your add-in. You'll need to use the browser developer tools to debug your code in Excel on the web. You cannot debug the desktop version of Excel using the command line.

From the command line run npm run watch to watch for and rebuild when code changes occur.
Open a second command line window (the first one will be blocked while running the watch.)
If you want to start your add-in in the desktop version of Excel, run the following command.

npm run start:desktop

Or if you prefer to start your add-in in Excel on the web run the following command.

npm run start:web -- --document {url} (where {url} is the URL of an Excel file on OneDrive or SharePoint)

Note

If you are developing on a Mac, enclose the {url} in single quotation marks. Do not do this on Windows.

If your add-in doesn't sideload in the document, follow the steps in Sideload your add-in to sideload your add-in. Then continue to the next section to start debugging.
Open developer tools in the browser. For Chrome and most browsers F12 will open the developer tools.
In developer tools, open your source code script file (functions.js or functions.ts). Your custom functions code may be located near the end of the file.
In the custom function source code, apply a breakpoint by selecting a line of code.

If you need to change the code you can make edits in Visual Studio and save the changes. Refresh the browser to see the changes loaded.

Commands for building and running your add-in

There are several build tasks available.

npm run watch: builds for development and automatically rebuilds when a source file is saved
npm run build-dev: builds for development once
npm run build: builds for production
npm run dev-server: runs the web server used for development

You can use the following tasks to start debugging on desktop or online.

npm run start:desktop: Starts Excel on desktop and sideloads your add-in.
npm run start:web -- --document {url} (where {url} is the URL of an Excel file on OneDrive or SharePoint): Starts Excel on the web and sideloads your add-in.

Note

If you are developing on a Mac, enclose the {url} in single quotation marks. Do not do this on Windows.
npm run stop: Stops Excel and debugging.

Next steps

Learn about Authentication for custom functions without a shared runtime.