Custom functions debugging in a non-shared runtime

This article covers debugging only for custom functions that don't use a shared runtime. For shared runtime scenarios, see Overview of debugging Office Add-ins.

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.

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

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 Windows and macOS.

Run your add-in from Visual Studio Code

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

Sideload your add-in

1. Open Office on the web.

2. Open a new Excel workbook.

3. Select Home > Add-ins, then select More Settings.

4. On the Office Add-ins dialog, select Upload My Add-in.

5. Browse to the add-in manifest file, and then select Upload.

   

Start debugging

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

If you need to make changes, edit the code in VS Code, save your work, then refresh the workbook page to apply the update.

Use the command line tools to debug

If you don't use VS Code, run your add-in from the command line using tools such as Bash or PowerShell. To debug your code in Excel on the web, use your browser's developer tools.

1. From the command line run npm run watch to watch for and rebuild when code changes occur.

2. Open a second command line window (the first one is busy while running the watch.)

3. If you want to start your add-in in the desktop version of Excel and the "scripts" section of the project's package.json file has a "start:desktop" script, then run npm run start:desktop; otherwise, run npm run start.

   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. Then continue to the next section to start debugging.

4. Open your browser's developer tools. In Chrome and most browsers, press F12 to open the developer tools.

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

6. 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 VS Code and save the changes. Refresh the browser to see the changes loaded.

Commands for building and running your add-in

Available build tasks:

• 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

Use these tasks to start debugging:

• npm run start:desktop: Starts Excel on desktop and sideloads your add-in. If the "start:desktop" script isn't present in the "scripts" section of the project's package.json file, then run npm run start instead.

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

See also

• Custom functions troubleshooting
• Error handling for custom functions in Excel
• Create custom functions in Excel
• JavaScript-only runtime