Configure your Office Add-in to use a shared runtime

On desktop platforms, by default, your add-in runs code for ribbon buttons, custom functions, and the task pane in separate runtime environments. This creates limitations, such as not being able to easily share global data, and not being able to access all CORS functionality from a custom function.

However, you can configure your Office Add-in to share code in the same runtime (referred to as a shared runtime). This enables better coordination across your add-in and access to the task pane DOM and CORS from all parts of your add-in.

Configuring a shared runtime enables the following scenarios.

• Your Office Add-in can use additional UI features.
  • Change the availability of add-in commands
  • Run code in your Office Add-in when the document opens
  • Show or hide the task pane of your Office Add-in
  • Add custom keyboard shortcuts to your Office Add-ins (supported in Excel, PowerPoint, and Word add-ins)
• The following are available for Excel add-ins only.
  • Create custom contextual tabs in Office Add-ins
  • Custom functions have full CORS support.
  • Custom functions can call Office.js APIs to read spreadsheet document data.

This article steps through the process of configuring an add-in to use a shared runtime.

Create the add-in project

To learn how to convert an add-in to use a shared runtime, start by creating an add-in project that isn't already configured to used a shared runtime to use as a continuing example. Use the Agents Toolkit to create a task pane project, not a custom function project. Instructions are in Create Office Add-in projects with Microsoft 365 Agents Toolkit.

Configure the manifest

Follow these steps to configure a project to use a shared runtime. The continuing example project uses the unified manifest.

Configure the webpack.config.js file

In the continuing example, and probably in an existing add-in, the webpack.config.js builds multiple runtime loaders. You need to modify it to load only the shared runtime via the taskpane.html file.

1. Open the webpack.config.js file.

2. If your webpack.config.js file has the following commands.html plugin code, remove it.

   new HtmlWebpackPlugin({
       filename: "commands.html",
       template: "./src/commands/commands.html",
       chunks: ["polyfill", "commands"]
     })
   

3. If you're configuring an existing custom functions add-in to use a shared runtime, then the webpack.config.js file has the following functions.html plugin code, remove it.

   new HtmlWebpackPlugin({
       filename: "functions.html",
       template: "./src/functions/functions.html",
       chunks: ["polyfill", "functions"]
     })
   

4. If your project used either the functions or commands chunks, add them to the chunks list for the task pane as shown in the following code.

     new HtmlWebpackPlugin({
       filename: "taskpane.html",
       template: "./src/taskpane/taskpane.html",
       chunks: ["polyfill", "taskpane", "commands", "functions"]
     })
   

5. Save your changes and rebuild the project.

   npm run build
   

Test your Office Add-in changes

Confirm that you're using the shared runtime correctly with the following steps.

1. Open the taskpane.js file.

2. Comment out the existing code in the file and then add the following code. This code displays a count of how many times the task pane has been opened. Adding the onVisibilityModeChanged event is only supported in a shared runtime.

   /*global document, Office*/
   
   let _count = 0;
   
   Office.onReady(() => {
     document.getElementById("sideload-msg").style.display = "none";
     document.getElementById("app-body").style.display = "flex";
   
     updateCount(); // Update count on first open.
     Office.addin.onVisibilityModeChanged((args) => {
       if (args.visibilityMode === Office.VisibilityMode.taskpane) {
         updateCount(); // Update count on subsequent opens.
       }
     });
   });
   
   function updateCount() {
     _count++;
     document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
   }
   

3. Save your changes and run the project.

   npm start
   

Each time you open the task pane, the count of how many times it has been opened is incremented. The value of _count isn't be lost because the shared runtime keeps your code running even when the task pane is closed.

When you're finished testing, follow best practices to stop the dev server and uninstall the add-in as described at Use your tool's uninstall facility. Then restore the original code of taskpane.js.

Good practice: avoid multiple task panes

A shared runtime only supports one task pane, although that task pane can have more than one page. Implementing this practice depends on the type of manifest.

• Unified manifest for Microsoft 365: In the runtime object that is configured with a "long" lifetime, none of the objects in the "actions" array should have a "view" property.
• Add-in only manifest: In the ancestor <Host> element that has a descendant <Runtime> element that is set to a long lifetime, none of the descendant <Action> elements should have a <TaskpaneID> child element.

See also

• Call Excel APIs from a custom function
• Add custom keyboard shortcuts to your Office Add-ins
• Create custom contextual tabs in Office Add-ins
• Change the availability of add-in commands
• Run code in your Office Add-in when the document opens
• Show or hide the task pane of your Office Add-in
• Tutorial: Share data and events between Excel custom functions and the task pane
• Runtimes in Office Add-ins